🚀 chore(release): WP Bones 3.1.0

components/Home/Console.tsx

@@ -8,7 +8,7 @@ import classes from './Console.module.css';
 /**
  * `php bones` as it answers with no arguments: the command list, word for
  * word, from the CLI's own help (WPBones/src/Console/bin/bones, lines
- * 1701-1731, at v3.0.0). Grouped as the CLI groups them.
+ * 1838-1870, at v3.1.0). Grouped as the CLI groups them.
  */
 const GROUPS: { name: string | null; commands: [string, string][] }[] = [
   {
@@ -53,6 +53,10 @@ const GROUPS: { name: string | null; commands: [string, string][] }[] = [
       ['make:widget', 'Create a new Widget service provider class'],
     ],
   },
+  {
+    name: 'stub',
+    commands: [['stub:publish', 'Copy the stubs into stubs/, where make:* reads them first']],
+  },
 ];
 
 const COMMAND_COUNT = GROUPS.reduce((sum, group) => sum + group.commands.length, 0);

components/Home/WhatsNew.tsx

@@ -20,16 +20,16 @@ import classes from './WhatsNew.module.css';
  * l'accento sulle nuove feature che abbiamo introdotto nelle ultime versioni
  * -- scava a fondo -- tipo ad esempio i test"). Every line is the release
  * notes' or the docs' own (github.com/wpbones/WPBones/releases, v2.0.0 to
- * v3.0.0) and every figure was measured, not read off a note: the test counts
- * by running PHPUnit at each tag (`--list-tests`) and at v3.0.0 in full
- * ("OK (350 tests, 897 assertions)": 224 unit, 126 console), as on CI. They are
- * figures AT v3.0.0, said so on the page, so a later release does not make
+ * v3.1.0) and every figure was measured, not read off a note: the test counts
+ * by running PHPUnit at each tag (`--list-tests`) and at v3.1.0 in full
+ * ("OK (360 tests, 993 assertions)": 224 unit, 136 console), as on CI. They are
+ * figures AT v3.1.0, said so on the page, so a later release does not make
  * them false.
  */
 const RELEASE = (tag: string) => `https://github.com/wpbones/WPBones/releases/tag/${tag}`;
 
-/** v2.0.0 to v3.0.0, as `gh release list -R wpbones/WPBones` lists them. */
-const RELEASES = 18;
+/** v2.0.0 to v3.1.0, as `gh release list -R wpbones/WPBones` lists them. */
+const RELEASES = 19;
 
 /**
  * The suite at the four tags that grew it most, by `phpunit --list-tests` on the tag's tree. The
@@ -43,8 +43,8 @@ const GROWTH: [string, number][] = [
   ['v2.1.2', 200],
   ['v3.0.0', 350],
 ];
-const TESTS = 350;
-const ASSERTIONS = 897;
+const TESTS = 360;
+const ASSERTIONS = 993;
 /** .github/workflows/tests.yml's matrix. */
 const PHP = ['8.1', '8.2', '8.3', '8.4'];
 
@@ -155,15 +155,15 @@ export function WhatsNew() {
           <h3 className={home.h3}>Tested on every pull request</h3>
           <p className={home.body}>
             224 unit tests check the SQL the framework builds and who may open its pages, with no
-            WordPress and no database. 126 more run the real{' '}
+            WordPress and no database. 136 more run the real{' '}
             <code className={home.code}>bones</code> file against throwaway plugins. Every pull
             request and every push to master runs them on PHP 8.1 to 8.4, and a deprecation fails
             the build.
           </p>
 
           <dl className={classes.stats}>
             <div>
-              <dt>tests at v3.0.0</dt>
+              <dt>tests at v3.1.0</dt>
               <dd>
                 <ScrollNumber value={TESTS} />
               </dd>

content/bones-console/bones-console.mdx

@@ -483,4 +483,38 @@ The command refuses names that collide with WordPress core script handles
 handle is already registered by core, `wp_enqueue_script` silently drops
 your bundle and the app never mounts. Pick a distinctive name like
 `admin-ui`, `analytics`, or a plugin-specific prefix.
-</Callout>
+</Callout>
+
+### Customizing the stubs
+
+Every creator fills a stub: a template with placeholders such as `{Namespace}` and `{ClassName}`. Since `v3.1.0` a stub in your plugin's `stubs/` folder comes first. `make:controller` reads `stubs/controller.stub` when it is there, and says so (`Using stubs/controller.stub`), and the framework's own otherwise. Start from the framework's:
+
+```sh copy
+php bones stub:publish                   # every stub
+php bones stub:publish controller model  # only these
+```
+
+`stub:publish` never replaces a stub that is already in `stubs/`, since it is usually one you have edited: pass `--force` to take the framework's again, and your changes go. `deploy` leaves the `.stub` files out of the package.
+
+A published stub no longer follows the framework's. After `composer update wpbones/wpbones`, compare yours with `vendor/wpbones/wpbones/src/Console/stubs/`.
+
+| Stub | Written by | Placeholders |
+| --- | --- | --- |
+| `ajax` | `make:ajax` | `{Namespace}`, `{ClassName}`, `{Path}` |
+| `api` | `make:api` | `{Namespace}`, `{ClassName}`, `{Path}` |
+| `app` | `make:app` | `{AppName}`, `{ComponentName}`, `{TextDomain}` |
+| `command` | `make:console` | `{Namespace}`, `{ClassName}`, `{Signature}`, `{CommandName}` |
+| `controller` | `make:controller` | `{Namespace}`, `{ClassName}`, `{Path}` |
+| `cpt` | `make:cpt` | `{Namespace}`, `{ClassName}`, `{Path}`, `{ID}`, `{Name}`, `{Plural}` |
+| `ctt` | `make:ctt` | `{Namespace}`, `{ClassName}`, `{Path}`, `{ID}`, `{Name}`, `{Plural}`, `{ObjectType}` |
+| `eloquent-model` | `make:eloquent-model` | `{Namespace}`, `{ClassName}`, `{Path}`, `{Table}` |
+| `kernel` | `make:console`, when the plugin has no `plugin/Console/Kernel.php` yet | `{Namespace}`, `{ClassName}` |
+| `migrate` | `migrate:create` | `{Namespace}`, `{Tablename}` |
+| `model` | `make:model` | `{Namespace}`, `{ClassName}`, `{Path}` |
+| `provider` | `make:provider` | `{Namespace}`, `{ClassName}`, `{Path}` |
+| `schedule` | `make:schedule` | `{Namespace}`, `{ClassName}`, `{Path}` |
+| `shortcode` | `make:shortcode` | `{Namespace}`, `{ClassName}`, `{Path}` |
+| `widget` | `make:widget` | `{Namespace}`, `{ClassName}`, `{Path}`, `{PluginName}`, `{Slug}`, `{WidgetId}`, `{WidgetName}` |
+| `webpack-config`, `tsconfig`, `jest-config`, `prettierrc`, `prettierignore` | `migrate:to-v2`, for the files a plugin does not have yet | none |
+
+`{Namespace}` is your plugin's namespace, `{ClassName}` the class without its folder, and `{Path}` the sub-namespace of the folder: `\Shop` for `Shop/Cart`, empty for `Cart`.

package.json

@@ -79,5 +79,5 @@
     "test": "yarn next typegen && yarn format:test && yarn lint && yarn typecheck && yarn jest",
     "typecheck": "tsc --noEmit"
   },
-  "version": "3.0.0"
+  "version": "3.1.0"
 }