DOC Document changes to CLI interaction

silverstripe · Sep 16, 2024 · 70249e8 · 70249e8
1 parent 322df84
commit 70249e8
Show file tree

Hide file tree

Showing 21 changed files with 556 additions and 203 deletions.
diff --git a/en/00_Getting_Started/00_Server_Requirements.md b/en/00_Getting_Started/00_Server_Requirements.md
@@ -94,7 +94,7 @@ relevant i18n `lang` directories.
 
 Silverstripe CMS allows CMS authors to upload files into the `public/assets/` folder, which should be served by your
 webserver. **No PHP execution should be allowed in this folder**. This is configured for Apache by default
-via `public/assets/.htaccess`. The file is generated dynamically during the `dev/build` stage.
+via `public/assets/.htaccess`. The file is generated dynamically when building the database.
 
 Additionally, access is whitelisted by file extension through a dynamically generated whitelist based on
 the `File.allowed_extensions` setting

diff --git a/en/00_Getting_Started/03_Environment_Management.md b/en/00_Getting_Started/03_Environment_Management.md
@@ -130,5 +130,5 @@ Silverstripe core environment variables are listed here, though you're free to d
 | `SS_MANIFESTCACHE` | The manifest cache to use (defaults to file based caching). Must be a `Psr\Cache\CacheItemPoolInterface`, `Psr\SimpleCache\CacheInterface`, or `SilverStripe\Core\Cache\CacheFactory` class implementation. |
 | `SS_IGNORE_DOT_ENV` | If set, the `.env` file will be ignored. This is good for live to mitigate any performance implications of loading the `.env` file. |
 | `SS_BASE_URL` | The URL to use when it isn't determinable by other means (for example for CLI commands). Should either start with a protocol (e.g. `https://www.example.com`) or with a double forward slash (e.g. `//www.example.com`). |
-| `SS_FLUSH_ON_DEPLOY` | Try to detect deployments through file system modifications and flush on the first request after every deploy. Does not run "dev/build" - only "flush". Possible values are `true` (check for a framework PHP file modification time), `false` (no checks, skip deploy detection) or a path to a specific file or folder to be checked. See [DeployFlushDiscoverer](api:SilverStripe\Core\Startup\DeployFlushDiscoverer) for more details.<br /><br />False by default. |
+| `SS_FLUSH_ON_DEPLOY` | Try to detect deployments through file system modifications and flushes the cache on the first request after every deploy. Note this does not trigger buildin the database. Possible values are `true` (check for a framework PHP file modification time), `false` (no checks, skip deploy detection) or a path to a specific file or folder to be checked. See [DeployFlushDiscoverer](api:SilverStripe\Core\Startup\DeployFlushDiscoverer) for more details.<br /><br />False by default. |
 | `SS_TEMP_PATH` | File storage used for the default cache adapters in [Manifests](/developer_guides/execution_pipeline/manifests), [Object Caching](/developer_guides/performance/caching) and [Partial Template Caching](/developer_guides/templates/partial_template_caching). Can be an absolute path (with a leading `/`), or a path relative to the project root. Defaults to creating a sub-directory of PHP's built-in `sys_get_temp_dir()` or using the `silverstripe-cache` directory relative to the project root if one is present. |
diff --git a/en/00_Getting_Started/index.md b/en/00_Getting_Started/index.md
@@ -48,13 +48,15 @@ SS_ENVIRONMENT_TYPE="<dev|test|live>"
 Now you should be able to build your database by running this command:
 
 ```bash
-vendor/bin/sake dev/build
+vendor/bin/sake db:build
 ```
 
+> [!TIP]
+> Check out [Sake](/developer_guides/cli/sake) for more details about using Sake on the command line
+
 Your website should be available on your domain now (e.g. `https://www.example.com`). The CMS login can be accessed at `/admin` (e.g. `http://www.example.com/admin`).
 
-For more information on how to maintain your installation or install projects, check
-out [Using Silverstripe with Composer](composer).
+For more information on how to maintain your installation or install projects, check out [Using Silverstripe with Composer](composer).
 
 ## Keep learning
 

diff --git a/en/02_Developer_Guides/00_Model/01_Data_Model_and_ORM.md b/en/02_Developer_Guides/00_Model/01_Data_Model_and_ORM.md
@@ -52,10 +52,10 @@ so on. After writing this class, we need to regenerate the database schema.
 
 After adding, modifying or removing `DataObject` subclasses, make sure to rebuild your Silverstripe CMS database. The
 database schema is generated automatically by visiting `/dev/build` (e.g. `https://www.example.com/dev/build`) in your browser
-while authenticated as an administrator, or by running `sake dev/build` on the command line (see [Command Line Interface](/developer_guides/cli/) to learn more about `sake`).
+while authenticated as an administrator, or by running `sake db:build` on the command line (see [Sake](/developer_guides/cli/sake/) to learn more about using Sake).
 
 > [!NOTE]
-> In "dev" mode, you do not need to be authenticated to run `/dev/build`. See [Environment Types](/developer_guides/debugging/environment_types) for more information.
+> In "dev" mode, you do not need to be authenticated to visit `/dev/build`. See [Environment Types](/developer_guides/debugging/environment_types) for more information.
 
 This script will analyze the existing schema, compare it to what's required by your data classes, and alter the schema
 as required.

diff --git a/en/02_Developer_Guides/00_Model/02_Relations.md b/en/02_Developer_Guides/00_Model/02_Relations.md
@@ -1191,7 +1191,7 @@ for displaying the objects contained in the relation.
 
 The [`RelationValidationService`](api:SilverStripe\Dev\Validation\RelationValidationService) can be used to check if your relations are set up according to best practices, and is very useful for debugging unexpected behaviour with relations. It is disabled by default.
 
-To enable this service, set the following YAML configuration, which will give you validation output every time you run `dev/build`.
+To enable this service, set the following YAML configuration, which will give you validation output every time you run `sake db:build`.
 
 ```yml
 SilverStripe\Dev\Validation\RelationValidationService:
@@ -1228,7 +1228,7 @@ SilverStripe\Dev\Validation\RelationValidationService:
     - 'App\Model\Player.Teams'
 ```
 
-### Validating relations outside dev/build
+### Validating relations any time
 
 If you want to, you can invoke the `RelationValidationService` at any time in PHP code.
 

diff --git a/en/02_Developer_Guides/00_Model/12_Indexes.md b/en/02_Developer_Guides/00_Model/12_Indexes.md
@@ -96,8 +96,8 @@ other columns. If this is indexed, smaller and reasonably unique it might be fas
 
 ## Index creation/destruction
 
-Indexes are generated and removed automatically during a `dev/build`. Caution if you're working with large tables and
-modify an index as the next `dev/build` will `DROP` the index, and then `ADD` it.
+Indexes are generated and removed automatically when building the database. Caution if you're working with large tables and
+modify an index as the next time the database is built it will `DROP` the index, and then `ADD` it.
 
 ## API documentation
 

diff --git a/en/02_Developer_Guides/00_Model/How_Tos/Dynamic_Default_Fields.md b/en/02_Developer_Guides/00_Model/How_Tos/Dynamic_Default_Fields.md
@@ -104,7 +104,7 @@ class Dog extends DataObject
 
 ## Static default records
 
-The [DataObject::$default_records](api:SilverStripe\ORM\DataObject::$default_records) array allows you to specify default records created on dev/build.
+The [DataObject::$default_records](api:SilverStripe\ORM\DataObject::$default_records) array allows you to specify default records created when the database is built.
 
 A simple example of this is having a region model and wanting a list of regions created when the site is built:
 

diff --git a/en/02_Developer_Guides/03_Forms/How_Tos/05_Simple_Contact_Form.md b/en/02_Developer_Guides/03_Forms/How_Tos/05_Simple_Contact_Form.md
@@ -85,7 +85,7 @@ To show the form on the page, we need to render it in our template. We do this b
 
 The reason it's standard practice to name the form function 'Form' is so that we don't have to create a separate template for each page with a form. By adding $Form to the generic Page.ss template, all pages with a form named 'Form' will have their forms shown.
 
-If you now create a ContactPage in the CMS (making sure you have rebuilt the database and flushed the templates /dev/build?flush=all) and visit the page, you will now see a contact form.
+If you now create a ContactPage in the CMS (making sure you have rebuilt the database and flushed the templates e.g. `sake db:build --flush`) and visit the page, you will now see a contact form.
 
 ![a form with three text fields ("name", "email", and "message") and a submit button](../../../_images/howto_contactForm.jpg)
 

diff --git a/en/02_Developer_Guides/04_Configuration/01_SiteConfig.md b/en/02_Developer_Guides/04_Configuration/01_SiteConfig.md
@@ -68,8 +68,7 @@ Silverstripe\SiteConfig\SiteConfig:
 ```
 
 > [!WARNING]
-> After adding the class and the YAML change, make sure to rebuild your database by visiting `https://www.example.com/dev/build`.
-> You may also need to reload the screen with a `?flush=1` i.e.`https://www.example.com/admin/settings?flush=1`.
+> After adding the class and the YAML change, make sure to rebuild your database and flush the cache by running `sake db:build --flush`.
 
 You can define as many extensions for `SiteConfig` as you need. For example, if you're developing a module and want to
 provide the users a place to configure site-wide settings then the `SiteConfig` panel is the place to go it.

diff --git a/en/02_Developer_Guides/05_Extending/00_Modules.md b/en/02_Developer_Guides/05_Extending/00_Modules.md
@@ -52,7 +52,7 @@ To lock down to a specific version, branch or commit, read up on
 ["lock" files](https://getcomposer.org/doc/01-basic-usage.md#commit-your-composer-lock-file-to-version-control).
 
 > [!WARNING]
-> After you add or remove modules, make sure you rebuild the database, class and configuration manifests by going to `https://www.example.com/dev/build?flush=1`
+> After you add or remove modules, make sure you rebuild the database and flush the cache by running `sake db:build --flush`
 
 ## Creating a module {#create}
 

diff --git a/en/02_Developer_Guides/06_Testing/00_Unit_Testing.md b/en/02_Developer_Guides/06_Testing/00_Unit_Testing.md
@@ -72,7 +72,7 @@ application database. To provide seed data use a [Fixture](fixtures) file.
 
 > [!WARNING]
 > The test database is rebuilt every time one of the test methods is run and is removed afterwards. If the test is interrupted, the database will not be removed. Over time, you may have several hundred test
-> databases on your machine. To get rid of them, run `sake dev/tasks/CleanupTestDatabasesTask`.
+> databases on your machine. To get rid of them, run `sake tasks:CleanupTestDatabasesTask`.
 
 ## Custom PHPUnit configuration
 

diff --git a/en/02_Developer_Guides/07_Debugging/02_URL_Variable_Tools.md b/en/02_Developer_Guides/07_Debugging/02_URL_Variable_Tools.md
@@ -70,7 +70,7 @@ Redirections](/developer_guides/controllers/redirection) for more information an
  | URL Variable  | Values | Description |
  | ------------  | ------ | ----------- |
  | quiet         | 1      | Don't show messages during build |
- | dont_populate | 1      | Don't run **requireDefaultRecords()** on the models when building. This will build the table but not insert any records |
+ | no-populate   | 1      | Don't run **requireDefaultRecords()** on the models when building. This will build the table but not insert any records |
 
 ## Config diagnostic URLs
 

diff --git a/en/02_Developer_Guides/08_Performance/06_ORM.md b/en/02_Developer_Guides/08_Performance/06_ORM.md
@@ -25,12 +25,12 @@ SilverStripe\Forms\TreeDropdownField:
 
 See [SearchFilter Modifiers](/developer_guides/model/searchfilters/) for more information about search filters.
 
-## Skipping check and repair during dev/build {#skip-check-and-repair}
+## Skipping check and repair when the database is built {#skip-check-and-repair}
 
-When you run `dev/build`, there is a step that checks the integrity of the database tables (via `CHECK TABLE`) and repairs issues (via `REPAIR TABLE`) if possible.
+When you run `sake db:build`, there is a step that checks the integrity of the database tables (via `CHECK TABLE`) and repairs issues (via `REPAIR TABLE`) if possible.
 
 For tables with many records (tens/hundreds of thousands) this can be slow. If you identify that you have some specific `DataObject` models with lots of records
-which are slowing down your `dev/build`, you might want to explicitly skip checks for those:
+which are slowing down building the database, you might want to explicitly skip checks for those:
 
 ```yml
 SilverStripe\ORM\Connect\DBSchemaManager:

diff --git a/en/02_Developer_Guides/09_Security/00_Member.md b/en/02_Developer_Guides/09_Security/00_Member.md
@@ -175,23 +175,24 @@ For example:
 namespace App\Task;
 
 use App\Model\DataRecord;
-use BadMethodCallException;
-use SilverStripe\Control\Director;
 use SilverStripe\Dev\BuildTask;
+use SilverStripe\PolyExecution\PolyOutput;
 use SilverStripe\Security\Member;
 use SilverStripe\Security\Security;
+use Symfony\Component\Console\Command\Command;
+use Symfony\Component\Console\Input\InputInterface;
 
 class CleanRecordsTask extends BuildTask
 {
-    public function run($request)
+    private static bool $can_run_in_browser = false;
+
+    protected function execute(InputInterface $input, PolyOutput $output): int
     {
-        if (!Director::is_cli()) {
-            throw new BadMethodCallException('This task only runs on CLI');
-        }
         $admin = Security::findAnAdministrator();
         Member::actAs($admin, function () {
             DataRecord::get()->filter('Dirty', true)->removeAll();
         });
+        return Command::SUCCESS;
     }
 }
 ```

diff --git a/en/02_Developer_Guides/13_i18n/index.md b/en/02_Developer_Guides/13_i18n/index.md
@@ -294,32 +294,23 @@ otherwise it won't pick up locale changes.
 
 ## Collecting text
 
-To collect all the text in code and template files we have just to visit: `https://www.example.com/dev/tasks/i18nTextCollectorTask`
+To collect all the text in code and template files we have just to visit `https://www.example.com/dev/tasks/i18nTextCollectorTask` or run `sake tasks:i18nTextCollectorTask` on the command line.
 
 Text collector will then read the files, build the string table for each module where it finds calls to the
 underscore function, and tell you about the created files and any possible entity redeclaration.
 
 If you want to run the text collector for just one module you can use the 'module' parameter:
-`https://www.example.com/dev/tasks/i18nTextCollectorTask/?module=silverstripe%2Fcms`
+`https://www.example.com/dev/tasks/i18nTextCollectorTask/?module=silverstripe%2Fcms` or `sake tasks:i18nTextCollectorTask --module=silverstripe/cms`
 
 You can also run the text collector against multiple specific modules by separating the module names with a comma:
-`https://www.example.com/dev/tasks/i18nTextCollectorTask/?module=silverstripe%2Fcms,silverstripe%2Fframework`
+`https://www.example.com/dev/tasks/i18nTextCollectorTask/?module=silverstripe%2Fcms,silverstripe%2Fframework` or `sake tasks:i18nTextCollectorTask --module=silverstripe/cms,silverstripe/framework`
 
 > [!NOTE]
 > The `%2F` in `silverstripe%2Fcms` is a `/` which has been encoded for use in a URL in a non-ambiguous way.
 
 The text collector also collects text for themes - if you want to run text collection on a specific theme, reference the theme
 with prefix `themes:`, e.g:
-`https://www.example.com/dev/tasks/i18nTextCollectorTask/?module=themes:my-theme`
-
-> [!TIP]
-> You can also run this task via the command line using sake, e.g:
->
-> ```bash
-> sake dev/tasks/i18nTextCollectorTask module=themes:my-theme,silverstripe/framework
-> ```
->
-> See [the sake documentation](/developer_guides/cli/) for details about using sake.
+`https://www.example.com/dev/tasks/i18nTextCollectorTask/?module=themes:my-theme` or `sake tasks:i18nTextCollectorTask --module="themes:my-theme"`
 
 ## Module priority
 

diff --git a/...loper_Guides/15_Customising_the_Admin_Interface/How_Tos/Extend_CMS_Interface.md b/...loper_Guides/15_Customising_the_Admin_Interface/How_Tos/Extend_CMS_Interface.md
@@ -138,7 +138,7 @@ SilverStripe\CMS\Model\SiteTree:
     - App\Extension\BookmarkedPageExtension
 ```
 
-In order to add the field to the database, run a `dev/build/?flush=all`.
+In order to add the field to the database, run `sake db:build --flush`.
 Refresh the CMS, open a page for editing and you should see the new checkbox.
 
 ## Retrieve the list of bookmarks from the database

diff --git a/en/02_Developer_Guides/17_CLI/01_Sake.md b/en/02_Developer_Guides/17_CLI/01_Sake.md
@@ -0,0 +1,104 @@
+---
+title: Sake
+summary: Run commands against your Silverstripe CMS project on the command line
+icon: terminal
+---
+
+# Sake
+
+Sake is a CLI application powered by [`symfony/console`](https://symfony.com/doc/current/console.html).
+
+## Installation
+
+Sake can be invoked using `vendor/bin/sake` in your terminal of choice with no additional actions required.
+
+If you only have a single Silverstripe CMS project running on your server (for example in a production environment), you might want to add the `vendor/bin/` directory to your `$PATH` so you can invoke it simply as `sake`. Most documentation will assume you have done this, and will say to run `sake`, rather than `vendor/bin/sake`.
+
+You can get auto completion when typing commands if you are using a supported shell in your terminal. All commands support name and option completion, and some can even complete argument values. Run `sake completion --help` for instructions. You should only need to do this once (per user or per server, depending on how you configure it) and it will work for all projects on that server.
+
+After setting up completion (or if you never intend to set it up) you might want to hide the `completion` command from Sake's command list. You can do that with this YAML configuration:
+
+```yml
+SilverStripe\Cli\Sake:
+  hide_completion_command: true
+```
+
+## Configuration
+
+### Base URL
+
+Sometimes Silverstripe CMS needs to know the URL of your site. For example, when sending an email or generating static
+files. When you're visiting the site in a web browser this is easy to work out, but when executing scripts on the
+command line, it has no way of knowing.
+
+You can use the `SS_BASE_URL` environment variable to specify this.
+
+```bash
+SS_BASE_URL="https://www.example.com"
+```
+
+### Showing or hiding tasks from the command list
+
+Projects often end up with a lot of tasks, which can clutter the command list. Sake will automatically hide tasks from the main command list when there are too many tasks.
+
+You can configure the threshold for this behaviour with the [`Sake.max_tasks_to_display`](api:SilverStripe\Cli\Sake->max_tasks_to_display) configuration property:
+
+```yml
+SilverStripe\Cli\Sake:
+  max_tasks_to_display: 30
+```
+
+When there are more than that many tasks, the tasks will be hidden. Run `sake tasks` to see the full list at any time.
+
+You can set the value to `0` to *always* display the tasks in the main command list.
+
+### Adding commands
+
+There are two types of commands that can be added to Sake:
+
+- regular symfony commands
+- [`PolyCommand`](api:SilverStripe\PolyExecution\PolyCommand) subclasses
+
+Both of those can be added to Sake with the below configuration, but `PolyCommand` subclasses can also be added in a few other ways depending on their purpose. See [`PolyCommand`](/developer_guides/cli/polycommand) for more information about those.
+
+To add commands to Sake, add them to the [`Sake.commands`](api:SilverStripe\Cli\Sake->commands) configuration property:
+
+```yml
+SilverStripe\Cli\Sake:
+  commands:
+    - 'App\Cli\Command\MyCommand'
+```
+
+See [symfony/console documentation](https://symfony.com/doc/current/console.html#creating-a-command) for details about how to create a symfony command (though note the information about "registering the command" and "running the command" in that documentation doesn't apply to Sake).
+
+## Usage
+
+Run `sake help` at any time for information about how to use Sake.
+
+Here are some common commands you can run with Sake:
+
+```bash
+# list available commands
+sake # or `sake list`
+
+# list available tasks
+sake tasks
+
+# build the database
+sake db:build
+
+# flush the cache
+sake flush # or use the `--flush` flag with any other command
+
+# get help info about a command (including tasks)
+sake <command> --help # e.g. `sake db:build --help`
+```
+
+> [!CAUTION]
+> You should run `sake` with the same system user that runs your web server. Otherwise you will have a separate filesystem cache for CLI and you won't be able to flush or warm your webserver cache using Sake.
+
+Sake doesn't use your project's routing and controllers for normal execution, but if you do specifically need to access an HTTP route in your application from the CLI, you can use the `sake navigate` command.
+
+```bash
+sake navigate about-us/teams
+```