From 9aea31d68c63b7b834afb4140678aec95db1bdfd Mon Sep 17 00:00:00 2001 From: "Nathan J. Brauer" Date: Tue, 26 Mar 2024 21:22:15 -0700 Subject: [PATCH 1/2] NEW Added dev/task to initialise DataObjects for existing datasets New task is based on the original task built for SiteTree but is now extendable for any DataObject enabled with Fluent. To prevent duplicate code, the original task now extends the new task. --- .../InitialDataObjectLocalisationTask.php | 287 ++++++++++++++++++ src/Task/InitialPageLocalisationTask.php | 108 ++----- 2 files changed, 308 insertions(+), 87 deletions(-) create mode 100644 src/Task/InitialDataObjectLocalisationTask.php diff --git a/src/Task/InitialDataObjectLocalisationTask.php b/src/Task/InitialDataObjectLocalisationTask.php new file mode 100644 index 00000000..a8897e73 --- /dev/null +++ b/src/Task/InitialDataObjectLocalisationTask.php @@ -0,0 +1,287 @@ +exclude_classes`. + * @var string[] + */ + protected $include_only_classes = []; + + /** + * When extending this class, you may choose to exclude these specific classes. + * This is IGNORED if `$this->include_only_classes` is not empty. + * @var string[] + */ + protected $exclude_classes = [ + SiteTree::class + ]; + + /** + * @param HTTPRequest $request + * @return void + * @throws \ReflectionException + * @throws \SilverStripe\ORM\ValidationException + */ + public function run($request) + { + if (!Director::is_cli()) { + echo '
' . PHP_EOL;
+        }
+
+        $publish = (bool)$request->getVar('publish');
+        $limit = (int)$request->getVar('limit');
+
+        $total_results = [
+            'localisable' => 0,
+            'localised' => 0,
+            'publishable' => 0,
+            'published' => 0,
+        ];
+
+        /** @var Locale $globalLocale */
+        $globalLocale = Locale::get()
+            ->filter(['IsGlobalDefault' => 1])
+            ->sort('ID', 'ASC')
+            ->first();
+
+        if (!$globalLocale) {
+            echo 'Please set global locale first!' . PHP_EOL;
+
+            return;
+        }
+
+        if ($this->include_only_classes && is_array($this->include_only_classes)) {
+            $classesWithFluent = $this->include_only_classes;
+            foreach ($this->include_only_classes as $key => $dataClass) {
+                if (!$this->isClassNamePermitted($dataClass)) {
+                    echo sprintf('ERROR: `%s` does not have FluentExtension installed. Continuing without it...', $dataClass) . PHP_EOL;
+                    unset($classesWithFluent[$key]);
+                }
+            }
+        } else {
+            $dataClasses = static::getDirectSubclassesRecursivelyFor(DataObject::class);
+            $classesWithFluent = $this->filterPermittedClassesRecursively($dataClasses);
+        }
+
+        foreach ($classesWithFluent as $classWithFluent) {
+            if (!$this->isClassNamePermitted($classWithFluent)) {
+                continue;
+            }
+
+            $results = $this->doLocaliseClass($classWithFluent, $globalLocale, $limit, $publish);
+            foreach ($results as $key => $value) {
+                $total_results[$key] += $value;
+            }
+
+            echo sprintf('Processing %s objects...', $classWithFluent) . PHP_EOL;
+            echo sprintf('└─ Localised %d of %d objects.', $results['localised'], $results['localisable']) . PHP_EOL;
+            if ($results['publishable']) {
+                echo sprintf('└─ Published %d of %d objects.', $results['published'], $results['publishable']) . PHP_EOL;
+            }
+        }
+
+        echo PHP_EOL;
+        echo sprintf('Completed %d classes.', count($classesWithFluent)) . PHP_EOL;
+        echo sprintf('└─ Localised %d of %d objects in total.', $total_results['localised'], $total_results['localisable']) . PHP_EOL;
+        echo PHP_EOL;
+
+        if ($total_results['publishable']) {
+            echo sprintf('└─ Published %d of %d objects in total.', $total_results['published'], $total_results['publishable']) . PHP_EOL;
+            echo PHP_EOL;
+        }
+
+        if (!Director::is_cli()) {
+            echo '
'; + } + } + + /** + * @param $className + * @param $globalLocale + * @param $limit + * @param $publish + * @return array{localisable: int, localised: int, publishable: int, published: int} + * @throws \SilverStripe\ORM\ValidationException + */ + protected function doLocaliseClass($className, $globalLocale, $limit, $publish): array + { + $dataObjectIDs = FluentState::singleton()->withState(static function (FluentState $state) use ($className, $limit): array { + $state->setLocale(null); + $dataObjects = $className::get()->sort('ID', 'ASC'); + + if ($limit > 0) { + $dataObjects = $dataObjects->limit($limit); + } + + return $dataObjects->column('ID'); + }); + + return FluentState::singleton()->withState( + static function (FluentState $state) use ($className, $globalLocale, $publish, $dataObjectIDs): array { + $state->setLocale($globalLocale->Locale); + $return = [ + 'localisable' => 0, + 'localised' => 0, + 'publishable' => 0, + 'published' => 0, + ]; + + foreach ($dataObjectIDs as $dataObjectID) { + /** @var DataObject|FluentExtension $dataObject */ + $dataObject = $className::get()->byID($dataObjectID); + $return['localisable'] += 1; + + if (!$dataObject->hasExtension(FluentVersionedExtension::class)) { + if ($dataObject->existsInLocale()) { + continue; + } + $dataObject->write(); + $return['localised'] += 1; + continue; + } + + // We have versioned data, so start tracking how many have been published + $return['publishable'] += 1; + + /** @var DataObject|Versioned|FluentVersionedExtension $dataObject */ + if ($dataObject->isDraftedInLocale()) { + continue; + } + $dataObject->writeToStage(Versioned::DRAFT); + + $return['localised'] += 1; + + if (!$publish) { + continue; + } + + // Check if the base record was published - if not then we don't need to publish + // as this would leak draft content, we only want to publish pages which were published + // before Fluent module was added + $dataObjectID = $dataObject->ID; + $isBaseRecordPublished = FluentState::singleton()->withState( + static function (FluentState $state) use ($className, $dataObjectID): bool { + $state->setLocale(null); + $page = $className::get_by_id($dataObjectID); + + if ($page === null) { + return false; + } + + return $page->isPublished(); + } + ); + + if (!$isBaseRecordPublished) { + continue; + } + + $dataObject->publishRecursive(); + $return['published'] += 1; + } + + return $return; + } + ); + } + + /** + * @param string $className + * @return array[] + * @throws \ReflectionException + */ + protected static function getDirectSubclassesRecursivelyFor(string $className): array + { + $directSubclasses = []; + foreach (ClassInfo::subclassesFor($className, false) as $subclassName) { + $actualParentClass = get_parent_class($subclassName); + if ($className === $actualParentClass) { + $directSubclasses[$subclassName] = static::getDirectSubclassesRecursivelyFor($subclassName); + } + } + + return $directSubclasses; + } + + /** + * @param array $classes + * @return array + */ + protected function filterPermittedClassesRecursively(array $classes): array + { + $permittedClasses = []; + foreach ($classes as $parentClassName => $subclassNames) { + if ($this->isClassNamePermitted($parentClassName)) { + $permittedClasses[] = $parentClassName; + // We will skip all subclasses since the ORM will automatically + // pull them in when this parent is referenced + continue; + } + + $permittedClasses = array_merge($permittedClasses, $this->filterPermittedClassesRecursively($subclassNames)); + } + + return $permittedClasses; + } + + /** + * @param string $className + * @return bool + */ + protected function isClassNamePermitted(string $className): bool + { + // Do a simple (inexpensive) text comparison against the exclusion list before we create an object + if (!$this->include_only_classes && is_array($this->exclude_classes) && in_array($className, $this->exclude_classes)) { + return false; + } + + /** @var DataObject $dataObject */ + $dataObject = singleton($className); + + // Now we'll do a full comparison against the exclusion list + // This important step will, for example, match (refuse) a BlogPost if Page is listed as excluded + if (is_array($this->exclude_classes)) { + foreach ($this->exclude_classes as $excluded_class) { + if ($dataObject instanceof $excluded_class) { + return false; + } + } + } + + return $dataObject->hasExtension(FluentExtension::class); + } +} diff --git a/src/Task/InitialPageLocalisationTask.php b/src/Task/InitialPageLocalisationTask.php index 07724630..d39bd7bc 100644 --- a/src/Task/InitialPageLocalisationTask.php +++ b/src/Task/InitialPageLocalisationTask.php @@ -3,14 +3,8 @@ namespace TractorCow\Fluent\Task; use SilverStripe\CMS\Model\SiteTree; -use SilverStripe\Control\HTTPRequest; -use SilverStripe\Dev\BuildTask; -use SilverStripe\Versioned\Versioned; -use TractorCow\Fluent\Extension\FluentSiteTreeExtension; -use TractorCow\Fluent\Model\Locale; -use TractorCow\Fluent\State\FluentState; -class InitialPageLocalisationTask extends BuildTask +class InitialPageLocalisationTask extends InitialDataObjectLocalisationTask { /** * @var string @@ -20,94 +14,34 @@ class InitialPageLocalisationTask extends BuildTask /** * @var string */ - protected $title = 'Initial page localisation'; + protected $title = 'Initial SiteTree localisation'; /** * @var string */ - protected $description = 'Intended for projects which already have some pages when Fluent module is added.' . - ' This dev task will localise / publish all pages in the default locale. Locale setup has to be done before running this task.' . - ' Pages which are not published will not be published, only localised. Pages which are already localised will be skipped.'; + protected $description = 'Intended for projects which already have some Pages when Fluent module is added.' . + ' This dev task will localise / publish all Pages in the default locale. Locale setup has to be done before running this task.' . + ' Pass limit=N to limit number of records to localise. Pass publish=1 to force publishing of localised Pages.' . + ' Regardless, Pages which were not already published will not be published, only localised. Pages which were already localised will always be skipped.'; /** - * @param HTTPRequest $request + * @var string[] */ - public function run($request) - { - $publish = (bool) $request->getVar('publish'); - $limit = (int) $request->getVar('limit'); - - /** @var Locale $globalLocale */ - $globalLocale = Locale::get() - ->filter(['IsGlobalDefault' => 1]) - ->sort('ID', 'ASC') - ->first(); - - if (!$globalLocale) { - echo 'Please set global locale first!' . PHP_EOL; - - return; - } - - $pageIds = FluentState::singleton()->withState(static function (FluentState $state) use ($limit): array { - $state->setLocale(null); - $pages = SiteTree::get()->sort('ID', 'ASC'); - - if ($limit > 0) { - $pages = $pages->limit($limit); - } - - return $pages->column('ID'); - }); - - $localised = FluentState::singleton()->withState( - static function (FluentState $state) use ($globalLocale, $pageIds, $publish): int { - $state->setLocale($globalLocale->Locale); - $localised = 0; - - foreach ($pageIds as $pageId) { - /** @var SiteTree|FluentSiteTreeExtension $page */ - $page = SiteTree::get()->byID($pageId); - - if ($page->isDraftedInLocale()) { - continue; - } - - $page->writeToStage(Versioned::DRAFT); - $localised += 1; + protected $include_only_classes = [ + SiteTree::class + ]; - if (!$publish) { - continue; - } - - // Check if the base record was published - if not then we don't need to publish - // as this would leak draft content, we only want to publish pages which were published - // before Fluent module was added - $pageId = $page->ID; - $isBaseRecordPublished = FluentState::singleton()->withState( - static function (FluentState $state) use ($pageId): bool { - $state->setLocale(null); - $page = SiteTree::get_by_id($pageId); - - if ($page === null) { - return false; - } - - return $page->isPublished(); - } - ); - - if (!$isBaseRecordPublished) { - continue; - } - - $page->publishRecursive(); - } - - return $localised; - } - ); + /** + * @var string[] + */ + protected $exclude_classes = []; - echo sprintf('Localised %d pages.', $localised) . PHP_EOL; + /** + * Soft dependency on CMS module + * @return bool + */ + function isEnabled(): bool + { + return class_exists(SiteTree::class) && parent::isEnabled(); } } From 07328cf9f0dde51107916a4b4a3b5b922c4b48c5 Mon Sep 17 00:00:00 2001 From: "Nathan J. Brauer" Date: Tue, 2 Apr 2024 13:21:37 -0700 Subject: [PATCH 2/2] DOC Updated documentation for new DataObject initialisation task --- docs/en/migrating-from-single-language.md | 147 +++++++++++++++++----- 1 file changed, 119 insertions(+), 28 deletions(-) diff --git a/docs/en/migrating-from-single-language.md b/docs/en/migrating-from-single-language.md index 6fce063c..5137e43d 100644 --- a/docs/en/migrating-from-single-language.md +++ b/docs/en/migrating-from-single-language.md @@ -4,12 +4,14 @@ In case you want to add fluent to an existing site to add multi language functio ## Install fluent -use composer to install fluent, see [installation](installation.md) +Use composer to install fluent, see [installation](installation.md) ## Configure fluent -* add locales -You can either do this in the backend, or for the first setup you can utitlise `default_records` to add the locales to the db. +* Add locales + +You can either do this in the backend, or for the first setup you can utitlise `default_records` to add the locales to +the db. A fluent.yml might look like: ``` @@ -33,32 +35,121 @@ TractorCow\Fluent\Model\Locale: When you run `dev/build?flush` again, this adds the records to the database if the locales table is still empty. -## Publish available pages in your default locale +## Populating initial localised content for existing Pages and DataObjects in your default locale -Now your site is broken, cause no pages have been published and added as translated page in your default locale. -You can either publish all pages manually or use [publishall](https://docs.silverstripe.org/en/4/developer_guides/debugging/url_variable_tools/#building-and-publishing-urls) to publish all pages in bulk. -If you run `/admin/pages/publishall` in your browser your site will be fixed again and you can start adding translated content. +Now your site is broken because nothing has been published and added as translated data in your default locale. You can +either manually localise all DataObjects & Pages manually or use one of the automation options below. ### Automated tools for localisation -`InitialPageLocalisation` dev task can be used to either only localise or localise & publish your pages. -This dev task can be run either via CLI or queued as a job if Queued jobs module is installed. - -Localise only example - -``` -dev/tasks/initial-page-localisation-task -``` - -Localise & publish example - -``` -dev/tasks/initial-page-localisation-task publish=1 -``` - -Localisation in batches can be done by using the `limit` option. -Example below will localise & publish five pages on each run. - -``` -dev/tasks/initial-page-localisation-task publish=1&limit=5 -``` +#### From the CMS (SiteTree only) + +Use Silverstripe's +built-in [publishall](https://docs.silverstripe.org/en/4/developer_guides/debugging/url_variable_tools/#building-and-publishing-urls) +tool to publish all Pages in bulk. +Run `/admin/pages/publishall` in your browser and your site will be fixed again and you can start adding translated +content. + +_This method will work with Pages only (not localised DataObjects)._ + +#### Commandline or Queued Jobs (SiteTree and DataObjects) + +The `InitialPageLocalisation` and `InitialDataObjectLocalisationTask` dev tasks may be used to localise and, optionally, +publish your `Versioned` data (including Pages) from the commandline or queued as a job (if the Queued Jobs module is installed). + +`InitialPageLocalisation` - localise all `SiteTree` objects (Pages) + +`InitialDataObjectLocalisationTask` - localise all Fluent-enabled DataObjects (excluding `SiteTree`) + +1. Example: Localise all Pages (default, without publishing) + + ``` + dev/tasks/initial-page-localisation-task + ``` + +2. Example: Localise & publish all Pages + + ``` + dev/tasks/initial-page-localisation-task publish=1 + ``` + +3. Example: Localising Pages in batches can be done by using the `limit` option. + This will localise & publish five pages on each run. + + ``` + dev/tasks/initial-page-localisation-task publish=1&limit=5 + ``` + +4. Example: All the same functionality is available for localising all DataObjects, including `Versioned` and non-Versioned classes + + ``` + dev/tasks/initial-dataobject-localisation-task + ``` + or + + ``` + dev/tasks/initial-dataobject-localisation-task publish=1&limit=5 + ``` + +#### Customize your own initialisation dev task + +Perhaps you want to be more selective in how you initialise your localised content. +The `InitialDataObjectLocalisationTask` class can be easily extended to either list exactly which classes you want to +initially localise, or you can exclude specific classes from initialisation. + +1. **Initialise specific classes:** The following example will create a task which localises **_ONLY_** `BlogPost` +pages, `Testimonial` objects, _and their subclasses (if any)_. + + ```php + class CustomLocalisationTask extends InitialDataObjectLocalisationTask + { + /** + * @var string + */ + private static $segment = 'custom-localisation-initialisation-task'; + + /** + * @var string + */ + protected $title = 'Custom localisation initialisation'; + + /** + * @var string[] + */ + protected array $include_only_classes = [ + \SilverStripe\Blog\Model\BlogPost::class, + \AcmeCo\Model\Testimonial::class + ]; + + } + ``` + +2. **Initialise all DataObjects but exclude some:** The following example will create a task which localises **_ALL_** +DataObjects **_except_** `BlogPost` pages, `Testimonial` objects, _and their subclasses (if any)_. + + ```php + class CustomLocalisationTask extends InitialDataObjectLocalisationTask + { + /** + * @var string + */ + private static $segment = 'custom-localisation-initialisation-task'; + + /** + * @var string + */ + protected $title = 'Custom localisation initialisation'; + + /** + * @var string[] + */ + protected array $exclude_classes = [ + \SilverStripe\Blog\Model\BlogPost::class, + \AcmeCo\Model\Testimonial::class + ]; + + } + ``` + +3. **One or the other:** You may specify `$include_only_classes` OR `$exclude_classes` - not both. +If `$include_only_classes` is not an empty array, `$exclude_classes` will be ignored.