'a uuid, never changes', * 'name' => 'Plain text, 60 chars max, unique ignoring case', * 'request' => Request::to_array(), sanitised, no picked order IDs, * 'created' => unix time, * 'updated' => unix time, * 'author' => user ID that created it, * ] * * Only a sanitised request is ever written, and every read sanitises it * again, so a template saved by an older version (or a field an add-on no * longer registers) can never reach the exporter unchecked. Reads never * rewrite the option: switching that add-on back on brings the column back. */ final class Templates { public const OPTION = 'modulary_export_templates'; /** * Most templates one store keeps. Enough for every report a shop runs, * small enough that the header and the option stay light. */ public const MAX = 50; /** * Longest name, in characters. A name is a chip label, not a description. */ public const NAME_MAX = 60; /** * Every template, oldest first, each request re-sanitised. * * @return array, created: int, updated: int, author: int}> */ public static function all(): array { $out = []; foreach ( self::stored() as $template ) { $out[] = self::public_shape( $template ); } return $out; } /** * One template by id. * * @param string $id Template id. * @return array{id: string, name: string, request: array, created: int, updated: int, author: int}|null */ public static function get( string $id ): ?array { foreach ( self::stored() as $template ) { if ( $template['id'] === $id ) { return self::public_shape( $template ); } } return null; } /** * Save a new template. * * @param mixed $name Raw name. * @param mixed $request Raw export request, as the preview and download take it. * @return array{id: string, name: string, request: array, created: int, updated: int, author: int}|\WP_Error */ public static function create( mixed $name, mixed $request ): array|\WP_Error { $templates = self::stored(); if ( count( $templates ) >= self::MAX ) { return new \WP_Error( 'modulary_export_template_limit', /* translators: %d: most templates a store can keep */ sprintf( __( 'This store already has %d templates, the most it can keep. Delete one to save another.', 'modulary-export' ), self::MAX ), [ 'status' => 400 ] ); } $name = self::check_name( $name, $templates ); if ( $name instanceof \WP_Error ) { return $name; } if ( ! is_array( $request ) ) { return self::invalid_request(); } $now = time(); $template = [ 'id' => wp_generate_uuid4(), 'name' => $name, 'request' => self::storable( $request ), 'created' => $now, 'updated' => $now, 'author' => get_current_user_id(), ]; $templates[] = $template; self::write( $templates ); $saved = self::public_shape( $template ); /** * Fires after a template is created, renamed or updated. * * Pro's scheduled exports listen here: a schedule follows its * template by id, so a changed template changes the next run. * * @param array $template The template as saved (id, name, request, created, updated, author). * @param array|null $previous The template before this change; null when it was just created. */ do_action( 'modulary_export_template_saved', $saved, null ); return $saved; } /** * Rename a template, replace its export with new settings, or both. * Its id and creation time never change. * * @param string $id Template id. * @param mixed $name New name, or null to keep it. * @param mixed $request New export request, or null to keep it. * @return array{id: string, name: string, request: array, created: int, updated: int, author: int}|\WP_Error */ public static function update( string $id, mixed $name = null, mixed $request = null ): array|\WP_Error { $templates = self::stored(); $index = self::index_of( $id, $templates ); if ( null === $index ) { return self::not_found(); } $template = $templates[ $index ]; $previous = self::public_shape( $template ); if ( null !== $name ) { $name = self::check_name( $name, $templates, $id ); if ( $name instanceof \WP_Error ) { return $name; } $template['name'] = $name; } if ( null !== $request ) { if ( ! is_array( $request ) ) { return self::invalid_request(); } $template['request'] = self::storable( $request ); } $template['updated'] = time(); $templates[ $index ] = $template; self::write( $templates ); $saved = self::public_shape( $template ); /** This action is documented in src/Export/Templates.php */ do_action( 'modulary_export_template_saved', $saved, $previous ); return $saved; } /** * Delete a template. * * @param string $id Template id. * @return array{id: string, name: string, request: array, created: int, updated: int, author: int}|\WP_Error The deleted template. */ public static function delete( string $id ): array|\WP_Error { $templates = self::stored(); $index = self::index_of( $id, $templates ); if ( null === $index ) { return self::not_found(); } $deleted = self::public_shape( $templates[ $index ] ); array_splice( $templates, $index, 1 ); self::write( $templates ); /** * Fires after a template is deleted. * * Pro removes the template's schedules here. * * @param array $template The deleted template (id, name, request, created, updated, author). */ do_action( 'modulary_export_template_deleted', $deleted ); return $deleted; } /** * A name as it is stored: plain text on one line, single spaces, at most * NAME_MAX characters. Empty when nothing usable is left. * * @param mixed $name Raw name. */ public static function sanitize_name( mixed $name ): string { if ( ! is_string( $name ) ) { return ''; } $name = (string) preg_replace( '/\s+/u', ' ', sanitize_text_field( $name ) ); return trim( mb_substr( trim( $name ), 0, self::NAME_MAX ) ); } /** * Sanitise a name and make sure no other template has it. * * @param mixed $name Raw name. * @param array> $templates Stored templates. * @param string $except Id of the template being renamed. * @return string|\WP_Error */ private static function check_name( mixed $name, array $templates, string $except = '' ): string|\WP_Error { $name = self::sanitize_name( $name ); if ( '' === $name ) { return new \WP_Error( 'modulary_export_template_name_empty', __( 'Give the template a name.', 'modulary-export' ), [ 'status' => 400 ] ); } // "VAT report" and "vat report" would be two chips nobody can tell apart. $folded = mb_strtolower( $name ); foreach ( $templates as $template ) { if ( $template['id'] !== $except && mb_strtolower( $template['name'] ) === $folded ) { return new \WP_Error( 'modulary_export_template_name_taken', /* translators: %s: template name */ sprintf( __( 'There is already a template called ā€œ%sā€.', 'modulary-export' ), $template['name'] ), [ 'status' => 409 ] ); } } return $name; } /** * The request as stored: through Request (so only known fields, labels * and options survive), with plain arrays instead of the JSON objects * to_array() returns, and without picked order IDs. * * A selection from WooCommerce → Orders is a one-off; a template is a * recipe that a later run (or a schedule) applies to the orders of that * day. Keeping the IDs would export the same orders forever. * * @param array $raw Raw request. * @return array */ private static function storable( array $raw ): array { $request = Request::from_array( $raw )->to_array(); $request['filters']['ids'] = []; $request['labels'] = (array) $request['labels']; $request['options'] = (array) $request['options']; return $request; } /** * A stored template as the app and add-ons see it: the request sanitised * again, in the same JSON shape the preview endpoint returns. * * @param array{id: string, name: string, request: array, created: int, updated: int, author: int} $template Stored template. * @return array{id: string, name: string, request: array, created: int, updated: int, author: int} */ private static function public_shape( array $template ): array { $request = Request::from_array( $template['request'] )->to_array(); $request['filters']['ids'] = []; return [ 'id' => $template['id'], 'name' => $template['name'], 'request' => $request, 'created' => $template['created'], 'updated' => $template['updated'], 'author' => $template['author'], ]; } /** * The stored list, with anything malformed dropped. * * @return array, created: int, updated: int, author: int}> */ private static function stored(): array { $raw = get_option( self::OPTION, [] ); if ( ! is_array( $raw ) ) { return []; } $out = []; foreach ( $raw as $template ) { if ( ! is_array( $template ) || ! is_string( $template['id'] ?? null ) || '' === $template['id'] || ! is_string( $template['name'] ?? null ) || '' === $template['name'] || ! is_array( $template['request'] ?? null ) ) { continue; } $out[] = [ 'id' => $template['id'], 'name' => self::sanitize_name( $template['name'] ), 'request' => $template['request'], 'created' => (int) ( $template['created'] ?? 0 ), 'updated' => (int) ( $template['updated'] ?? 0 ), 'author' => (int) ( $template['author'] ?? 0 ), ]; } return $out; } /** * Save the list. Not autoloaded: only the export screen and Pro's * scheduler read it, so other admin pages and the storefront never load it. * * @param array> $templates Templates. */ private static function write( array $templates ): void { update_option( self::OPTION, array_values( $templates ), false ); } /** * Position of a template in the stored list. * * @param string $id Template id. * @param array> $templates Stored templates. */ private static function index_of( string $id, array $templates ): ?int { foreach ( $templates as $index => $template ) { if ( $template['id'] === $id ) { return $index; } } return null; } /** * Unknown id: deleted by someone else, or never existed. */ public static function not_found(): \WP_Error { return new \WP_Error( 'modulary_export_template_not_found', __( 'That template no longer exists. Someone may have deleted it.', 'modulary-export' ), [ 'status' => 404 ] ); } /** * The request is not an object. */ private static function invalid_request(): \WP_Error { return new \WP_Error( 'modulary_export_template_invalid_request', __( 'Invalid export request.', 'modulary-export' ), [ 'status' => 400 ] ); } }