diff --git a/content/bones-console/bones-console.mdx b/content/bones-console/bones-console.mdx index c89a468..a2ce4c5 100644 --- a/content/bones-console/bones-console.mdx +++ b/content/bones-console/bones-console.mdx @@ -36,6 +36,10 @@ Great! You are quite ready to start developing. Since `v2.0.10` every command exits with a non-zero status when it fails, and with `1` when you answer "no" to a confirmation or nothing answers it, as in a script; errors are written to stderr. To confirm from a script, pipe the answer: `echo y | php bones version 1.2.0`. + +Since `v2.1.0` bones works from any folder: `php my-plugin/bones make:controller Cart` writes into `my-plugin`, and a custom command still finds WordPress. A relative `deploy` path means the folder you typed it in. Up to `v2.0.12` bones had to be run from the plugin root: from anywhere else it could not read the plugin's `namespace` file and stopped with a `TypeError`. + + ### `deploy` When your plugin is ready, you can use the `deploy` bones command in order to create a new folder useful to submit your plugin to the wordpress.org repository. @@ -168,6 +172,8 @@ The `rename` command is used to rename the plugin namespace. You can use the `re php bones rename "My First WP Bones Plugin" ``` +Since `v2.1.0` the rename writes only the files whose content changes, and leaves binary files alone. Up to `v2.0.12` it rewrote every file of the plugin, and a compiled `.mo` catalogue came out corrupted, because a longer plugin id shifts its strings while the offset table stays put. + → See more about [Naming your Plugin](../getting-started/naming-your-plugin). ### `require` @@ -208,12 +214,18 @@ A value you `return` is printed, variables live until the session ends, and an e ### `update` -The `update` command is used to update the WP Bones framework. You can use the `update` command by running: +The `update` command updates the WP Bones framework and the packages it depends on: ```sh copy php bones update ``` +Since `v2.1.0` it runs `composer update wpbones/wpbones --with-dependencies` and exits with Composer's status. To update every package of your plugin, run `composer update`. + + +Up to `v2.0.12` the command deleted `vendor/wpbones/wpbones` first and then ran a full `composer update`: when Composer failed, without a network for example, the plugin was left with no framework at all. + + → After updating the WP Bones framework, have a look at the [Changelog](../release-notes) to see what's new.
→ And you may also check the [Core Plugin Files](../core-plugin-files/overview) to see if there are any changes. @@ -348,12 +360,16 @@ php bones migrate:to-v2 ``` The command removes `gulpfile.js` and `package-lock.json`, creates -`webpack.config.js`, `tsconfig.json`, `.prettierrc`, and `jest.config.js` +`webpack.config.js`, `tsconfig.json`, `.prettierrc`, `.prettierignore` and `jest.config.js` from the framework stubs, rewrites `package.json` scripts to the unified `dev/build/test/format/lint` block, drops gulp-era devDependencies, and installs the v2 set (`@wordpress/scripts ^31`, `typescript`, `glob`, -`less-loader`, `webpack-remove-empty-scripts`, `@types/react*`). Your -`resources/assets/` tree is left untouched — your code is preserved. +`less-loader`, `webpack-remove-empty-scripts`, `@types/react*`, and `prettier` +as `wp-prettier`). Your `resources/assets/` tree is left untouched — your code is preserved. + + +Since `v2.1.0` the migrated `format:check` is `prettier --check`, and it writes nothing. Up to `v2.0.12` it was `wp-scripts format --check`, and `wp-scripts format` ignores `--check`: the "check" reformatted the plugin, compiled bundles included, and exited 0. The new `.prettierignore` also keeps `format` away from `public/`. + After migration, run: @@ -379,6 +395,8 @@ php bones make:cpt MyCustomPostTypeClass Every creator that writes a PHP class takes a class name or `Folder/ClassName` (`make:console` takes a class name only, since the kernel loads `plugin/Console/Commands/*.php`), and the namespace follows the folder: `php bones make:controller Shop/Cart` writes `plugin/Http/Controllers/Shop/Cart.php` in `…\Http\Controllers\Shop`. `make:app`, below, takes an app name instead. +Since `v2.1.0` `make:widget Shop/RecentPosts` gives the widget the `id_base` `-shop-recent-posts`, the name ` Recent Posts` and a description. Up to `v2.0.12` every widget of a plugin got `-demo-widget`, so a second widget shared the first one's settings, and the description never showed. + Since `v2.0.10` the class creators never overwrite a file that already exists: they stop and leave it as it is. Pass `--force` to overwrite it. A name that is not a PHP class name, or that climbs out of the folder with `..`, is refused. `make:app` refuses an existing app, `--force` or not. diff --git a/content/bones-console/writing-commands.mdx b/content/bones-console/writing-commands.mdx index e1b8d2d..da66670 100644 --- a/content/bones-console/writing-commands.mdx +++ b/content/bones-console/writing-commands.mdx @@ -96,8 +96,9 @@ public function handle() `$this->plugin` is available from WP Bones **v2.0.8**. When your plugin is active it is the very instance WordPress created, so hooks are not registered twice; when it is not active, - `loadWordPress()` boots it for the command. Run the command from the plugin root: WordPress is - looked up three folders above it, and if it is not there `$this->plugin` stays `null`. + `loadWordPress()` boots it for the command. WordPress is looked up three folders above the plugin, + and if it is not there `$this->plugin` stays `null`. Since `v2.1.0` that works whatever folder + you run `php bones` from; up to `v2.0.12` only from the plugin root. ## Customizing Deploy diff --git a/content/core-plugin-files/overview.mdx b/content/core-plugin-files/overview.mdx index 210a2ba..e7c6964 100644 --- a/content/core-plugin-files/overview.mdx +++ b/content/core-plugin-files/overview.mdx @@ -3,7 +3,7 @@ import { Callout, FileTree } from 'nextra/components' # Core Plugin Files -This document explains how to update the WP Bones framework using the `php bones update` command, which executes a `composer update` along with other tasks. It highlights that only the framework is updated, not your plugin. The document provides an overview of the core plugin files included in the WP Bones boilerplate, noting that these files may undergo changes. It is advised checking for updates to these files if you have a plugin created with an earlier version of WP Bones. +This document explains how to update the WP Bones framework using the `php bones update` command, which runs `composer update wpbones/wpbones --with-dependencies`. It highlights that only the framework is updated, not your plugin. The document provides an overview of the core plugin files included in the WP Bones boilerplate, noting that these files may undergo changes. It is advised checking for updates to these files if you have a plugin created with an earlier version of WP Bones. ## Overview @@ -13,7 +13,7 @@ You can update the WP Bones framework by using the bones command: php bones update ``` -Under the hood, the bones command will execute a `composer update` along with other tasks. +Under the hood, the bones command runs `composer update wpbones/wpbones --with-dependencies`; the `post-autoload-dump` hook in your [`composer.json`](./composer-json) then runs `php bones rename --update`, which renames the new framework into your namespace. Of course, you are updating just the framework, not your plugin. In this section, you will find the latest versions of the files included in the WP Bones boilerplate. These files may undergo changes, including breaking changes. diff --git a/content/core-plugin-files/package-json.mdx b/content/core-plugin-files/package-json.mdx index 92bfeda..c0a48d3 100644 --- a/content/core-plugin-files/package-json.mdx +++ b/content/core-plugin-files/package-json.mdx @@ -16,7 +16,7 @@ auto-discovers everything under `resources/assets/`. "test": "wp-scripts test-unit-js", "test:watch": "wp-scripts test-unit-js --watch", "format": "wp-scripts format", - "format:check": "wp-scripts format --check", + "format:check": "prettier --check --ignore-path .prettierignore \"**/*.{js,jsx,json,ts,tsx,yml,yaml}\"", "lint": "wp-scripts lint-js resources/", "lint:style": "wp-scripts lint-style 'resources/**/*.{css,scss}'", "check-engines": "wp-scripts check-engines", @@ -35,6 +35,7 @@ auto-discovers everything under `resources/assets/`. "glob": "^11.0.0", "less": "^4.6.4", "less-loader": "^12.2.0", + "prettier": "npm:wp-prettier@3.0.3", "typescript": "^5.9.3", "webpack-remove-empty-scripts": "^1.1.0" } @@ -49,8 +50,8 @@ auto-discovers everything under `resources/assets/`. | `yarn build` | One-shot production build into `public/` | | `yarn test` | Runs Jest via `wp-scripts test-unit-js` on files under `__tests__/` | | `yarn test:watch` | Same as above, watch mode | -| `yarn format` | Prettier over `resources/` | -| `yarn format:check` | Prettier in check mode (CI-friendly) | +| `yarn format` | Prettier over the plugin's JS, TS, JSON and YAML, except what `.prettierignore` lists: `public/` and `build/`, `vendor/`, `composer.json` and `composer.lock`, and the translation JSON in `languages/` | +| `yarn format:check` | The same files, checked: exits 1 where `yarn format` would change something, and writes nothing | | `yarn lint` | ESLint over JS/TS in `resources/` | | `yarn lint:style` | stylelint over CSS/SCSS in `resources/` | diff --git a/content/core-plugin-files/webpack-config.mdx b/content/core-plugin-files/webpack-config.mdx index c198cbc..185119a 100644 --- a/content/core-plugin-files/webpack-config.mdx +++ b/content/core-plugin-files/webpack-config.mdx @@ -23,9 +23,13 @@ const IGNORE_DECLARATIONS = { ignore: '**/*.d.ts' }; // @wordpress/scripts has loader rules for .css and .scss/.sass only: the .less rule // reuses the scss loaders (CSS extraction, css-loader, PostCSS) with less-loader. -const sassRule = defaultConfig.module.rules.find((rule) => rule.test instanceof RegExp && rule.test.test('.scss')); +const sassRule = defaultConfig.module.rules.find( + (rule) => rule.test instanceof RegExp && rule.test.test('.scss') +); if (!sassRule) { - throw new Error('webpack.config.js: no .scss rule in the @wordpress/scripts config to build the .less rule from.'); + throw new Error( + 'webpack.config.js: no .scss rule in the @wordpress/scripts config to build the .less rule from.' + ); } const lessRule = { test: /\.less$/, @@ -42,10 +46,12 @@ function autoEntries() { const entries = {}; // React/TS apps — folder-based (for apps with multiple files) - glob.sync('resources/assets/apps/*/index.{ts,tsx,js,jsx}', IGNORE_DECLARATIONS).forEach((file) => { - const name = path.basename(path.dirname(file)); - entries[`apps/${name}`] = `./${file}`; - }); + glob + .sync('resources/assets/apps/*/index.{ts,tsx,js,jsx}', IGNORE_DECLARATIONS) + .forEach((file) => { + const name = path.basename(path.dirname(file)); + entries[`apps/${name}`] = `./${file}`; + }); // React/TS apps — single-file (for lightweight apps) glob.sync('resources/assets/apps/*.{ts,tsx,js,jsx}', IGNORE_DECLARATIONS).forEach((file) => { @@ -82,6 +88,7 @@ module.exports = { }, plugins: [ ...defaultConfig.plugins, + // Strips the empty `.js` that webpack would generate for pure-CSS entries. new RemoveEmptyScriptsPlugin(), ], }; diff --git a/content/getting-started/naming-your-plugin.mdx b/content/getting-started/naming-your-plugin.mdx index 4033d83..4d8d554 100644 --- a/content/getting-started/naming-your-plugin.mdx +++ b/content/getting-started/naming-your-plugin.mdx @@ -84,6 +84,8 @@ php bones rename --update Probably, you won't need to do that as the update flow is already in the composer file +Since `v2.1.0` `rename --update` renames `vendor/` only, which is what Composer has just installed: your plugin's own files are left alone. Up to `v2.0.12` it went through the whole rename again, and in a renamed plugin with an `index.php` in its root it moved that `index.php` over your main plugin file. + ```json copy ... diff --git a/content/migrating-to-v2.mdx b/content/migrating-to-v2.mdx index d02c311..634fcf2 100644 --- a/content/migrating-to-v2.mdx +++ b/content/migrating-to-v2.mdx @@ -39,9 +39,9 @@ constraint to `^2.0.0` after running the migrator. - `webpack.config.js` — a single file that scans `resources/assets/` and builds everything. - `tsconfig.json` — TypeScript ready out of the box (JS still works). -- `.prettierrc`, `jest.config.js`. +- `.prettierrc`, `.prettierignore`, `jest.config.js`. - `@wordpress/scripts ^31`, `typescript`, `glob`, `less-loader`, `webpack-remove-empty-scripts`, - `@types/react*`, `@wordpress/jest-preset-default` devDependencies. + `@types/react*`, `@wordpress/jest-preset-default` and `prettier` (as `wp-prettier`) devDependencies. ### Unified scripts @@ -53,7 +53,7 @@ constraint to `^2.0.0` after running the migrator. "test": "wp-scripts test-unit-js", "test:watch": "wp-scripts test-unit-js --watch", "format": "wp-scripts format", - "format:check": "wp-scripts format --check", + "format:check": "prettier --check --ignore-path .prettierignore \"**/*.{js,jsx,json,ts,tsx,yml,yaml}\"", "lint": "wp-scripts lint-js resources/", "lint:style": "wp-scripts lint-style 'resources/**/*.{css,scss}'" } diff --git a/content/services-provider/widgets.mdx b/content/services-provider/widgets.mdx index 9311853..0e5b913 100644 --- a/content/services-provider/widgets.mdx +++ b/content/services-provider/widgets.mdx @@ -16,7 +16,7 @@ You may create your own widget service provider by following the steps below: php bones make:widget MyWidget ``` -By default, the new provider will be created in the `plugin/Widgets` directory. Of course, you may create your Service Provider manually and in any directory you prefer. You have to change the namespace accordingly. +By default, the new provider will be created in the `plugin/Widgets` directory. Its base ID, name and description come from the class name: `MyWidget` in a plugin named "WP Kirk" gets `wp-kirk-my-widget`, "WP Kirk My Widget" and "The My Widget widget of WP Kirk" (since `v2.1.0`; before, every widget got the same base ID, and so the same settings). Of course, you may create your Service Provider manually and in any directory you prefer. You have to change the namespace accordingly. ```php filename="plugin/Widgets/MyWidget.php" copy 'WP Kirk Demo Widget Description' + 'description' => 'The My Widget widget of WP Kirk' ]; /** diff --git a/package.json b/package.json index 10e86e9..d141d3c 100644 --- a/package.json +++ b/package.json @@ -77,5 +77,5 @@ "test": "yarn next typegen && yarn format:test && yarn lint && yarn typecheck && yarn jest", "typecheck": "tsc --noEmit" }, - "version": "2.0.12" + "version": "2.1.0" } diff --git a/public/newsletter/wpbones-2.1.0-bones-update.png b/public/newsletter/wpbones-2.1.0-bones-update.png new file mode 100644 index 0000000..036c507 Binary files /dev/null and b/public/newsletter/wpbones-2.1.0-bones-update.png differ diff --git a/public/wpkirk-api-boilerplate.zip b/public/wpkirk-api-boilerplate.zip index 1f7bc40..b4fc00c 100644 Binary files a/public/wpkirk-api-boilerplate.zip and b/public/wpkirk-api-boilerplate.zip differ diff --git a/public/wpkirk-blade-boilerplate.zip b/public/wpkirk-blade-boilerplate.zip index 7f9df48..b327e16 100644 Binary files a/public/wpkirk-blade-boilerplate.zip and b/public/wpkirk-blade-boilerplate.zip differ diff --git a/public/wpkirk-boilerplate.zip b/public/wpkirk-boilerplate.zip index 59fb9e0..8053018 100644 Binary files a/public/wpkirk-boilerplate.zip and b/public/wpkirk-boilerplate.zip differ diff --git a/public/wpkirk-cpt-boilerplate.zip b/public/wpkirk-cpt-boilerplate.zip index 2f9b195..c836d64 100644 Binary files a/public/wpkirk-cpt-boilerplate.zip and b/public/wpkirk-cpt-boilerplate.zip differ diff --git a/public/wpkirk-cron-boilerplate.zip b/public/wpkirk-cron-boilerplate.zip index 2422ced..da7b8f2 100644 Binary files a/public/wpkirk-cron-boilerplate.zip and b/public/wpkirk-cron-boilerplate.zip differ diff --git a/public/wpkirk-database-boilerplate.zip b/public/wpkirk-database-boilerplate.zip index be2e535..e0aafdc 100644 Binary files a/public/wpkirk-database-boilerplate.zip and b/public/wpkirk-database-boilerplate.zip differ diff --git a/public/wpkirk-hooks-boilerplate.zip b/public/wpkirk-hooks-boilerplate.zip index 1354b63..c2df126 100644 Binary files a/public/wpkirk-hooks-boilerplate.zip and b/public/wpkirk-hooks-boilerplate.zip differ diff --git a/public/wpkirk-internationalization-boilerplate.zip b/public/wpkirk-internationalization-boilerplate.zip index 2c7d791..5707bf4 100644 Binary files a/public/wpkirk-internationalization-boilerplate.zip and b/public/wpkirk-internationalization-boilerplate.zip differ diff --git a/public/wpkirk-mantine-boilerplate.zip b/public/wpkirk-mantine-boilerplate.zip index cddd9a2..8a4725a 100644 Binary files a/public/wpkirk-mantine-boilerplate.zip and b/public/wpkirk-mantine-boilerplate.zip differ diff --git a/public/wpkirk-options-boilerplate.zip b/public/wpkirk-options-boilerplate.zip index c03bfcc..5fb74ae 100644 Binary files a/public/wpkirk-options-boilerplate.zip and b/public/wpkirk-options-boilerplate.zip differ diff --git a/public/wpkirk-packages-boilerplate.zip b/public/wpkirk-packages-boilerplate.zip index 3bb4076..e66cff6 100644 Binary files a/public/wpkirk-packages-boilerplate.zip and b/public/wpkirk-packages-boilerplate.zip differ diff --git a/public/wpkirk-reactjs-boilerplate.zip b/public/wpkirk-reactjs-boilerplate.zip index ff25de1..4d66c22 100644 Binary files a/public/wpkirk-reactjs-boilerplate.zip and b/public/wpkirk-reactjs-boilerplate.zip differ diff --git a/public/wpkirk-routes-boilerplate.zip b/public/wpkirk-routes-boilerplate.zip index 35afc39..353db7c 100644 Binary files a/public/wpkirk-routes-boilerplate.zip and b/public/wpkirk-routes-boilerplate.zip differ diff --git a/public/wpkirk-typescript-boilerplate.zip b/public/wpkirk-typescript-boilerplate.zip index a65f4b6..f2c480e 100644 Binary files a/public/wpkirk-typescript-boilerplate.zip and b/public/wpkirk-typescript-boilerplate.zip differ