Skip to content

Commit e40dd36

Browse files
passchnpasschn
authored
Merge pull request #19 from bor-attila/cake5-next
Cake5 - Next
2 parents f13d0e6 + 8bd650a commit e40dd36

19 files changed

Lines changed: 864 additions & 655 deletions

‎CHANGELOG.md‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,15 @@
11
# Changelog
22

3+
## v3.0.0
4+
5+
The new version changes the plugin architecture and requires some modifications. It's highly recommended to check the
6+
README.md
7+
8+
* Updated the plugin's configuration array
9+
* The methods `$this->ViteScripts->pluginScript($pluginName)` and `pluginCss()` were removed
10+
* The `$this->ViteScripts->css()` and `$this->ViteScripts->script()` were updated
11+
* The running environment MUST be defined explicitly or a detector should be used
12+
313
## v2.3.0
414

515
### Changed

‎README.md‎

Lines changed: 99 additions & 81 deletions
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ reloading.
88
In production mode, the Helper loads the bundled files. `@vitejs/plugin-legacy` is supported, which will
99
insert `nomodule`-tags for older browsers, e.g. older iOS devices, which do not support js modules.
1010

11-
> This readme is for **version 1.x.** If you are migrating from 0.x and something is unclear, read the Migration guide
11+
> This readme is for **version 3.x.** If you are migrating from 0.x and something is unclear, read the Migration guide
1212
> under `/docs`. Feel free to open an issue if you run into problems.
1313
1414
## Installation
@@ -17,12 +17,13 @@ You can install this plugin into your CakePHP application using [composer](https
1717

1818
### CakePHP Version Map
1919

20-
| CakePHP version | Plugin Version | Branch | min. PHP Version |
21-
|-----------------|----------------|--------|------------------|
22-
| ^3.10 | / | cake3 | ^7.4 |
23-
| ^4.2 | 0.x | master | ^7.4 |
24-
| ^4.2 | 1.x | master | ^8.0 |
25-
| ^5.0 | 2.x | cake5 | ^8.1 |
20+
| CakePHP version | Plugin Version | Branch | min. PHP Version |
21+
|-----------------|----------------|-------------|------------------|
22+
| ^3.10 | / | cake3 | ^7.4 |
23+
| ^4.2 | 0.x | master | ^7.4 |
24+
| ^4.2 | 1.x | master | ^8.0 |
25+
| ^5.0 | 2.x | cake5 | ^8.1 |
26+
| ^5.0 | 3.x | cake5-next | ^8.3 |
2627

2728
The recommended way to install the plugin is:
2829

@@ -62,13 +63,13 @@ These are the default view blocks in CakePHP.
6263
In your php-template or in layout you can import javascript files with:
6364

6465
```php
65-
<?php $this->ViteScripts->script($options) ?>
66+
<?php $this->ViteScripts->script('resources/main.ts') ?>
6667
```
6768

68-
… or by using this shortcut for a single entrypoint:
69+
… or multiple files
6970

7071
```php
71-
<?php $this->ViteScripts->script('webroot_src/main.ts') ?>
72+
<?php $this->ViteScripts->script(['resources/main.ts', 'resources/main2.ts', 'resources/main3.ts']) ?>
7273
```
7374

7475
If you imported CSS files inside your JavaScript files, this method automatically
@@ -79,121 +80,138 @@ appends your css tags to the css view block.
7980
In your php-template you can import css files with:
8081

8182
```php
82-
<?php $this->ViteScripts->css($options) ?>
83+
<?php $this->ViteScripts->css('resources/style.css') ?>
8384
```
8485

85-
… or by using this shortcut for a single entrypoint:
86+
… or multiple files
8687

8788
```php
88-
<?php $this->ViteScripts->css('webroot_src/style.css') ?>
89+
<?php $this->ViteScripts->css(['resources/style.css', 'resources/style2.css', 'resources/style3.css']) ?>
8990
```
9091

9192
## Configuration
9293

9394
The plugin comes with some default configuration. You may need to change it depending on your setup. Or you might not
9495
need any config at all.
9596

96-
You can override some of these config settings through the `$options` of the helper methods. Or you can pass
97-
your own instance of `ViteHelperConfig` to a helper method as a second parameter.
97+
The default configuration is:
9898

9999
```php
100100
'ViteHelper' => [
101-
'build' => [
102-
'outDirectory' => false, // output directory of build assets. string (e.g. 'dist') or false.
103-
'manifest' => WWW_ROOT . 'manifest.json', // absolute path to manifest
104-
],
101+
'environment' => \ViteHelper\Enum\Environment::PRODUCTION, // available options PRODUCTION, DEVELOPMENT, FROM_DETECTOR
105102
'development' => [
106-
'scriptEntries' => ['someFolder/myScriptEntry.ts'], // relative to project root
107-
'styleEntries' => ['someFolder/myStyleEntry.scss'], // relative to project root. Unnecessary when using css-in-js.
108-
'hostNeedles' => ['.test', '.local'], // to check if the app is running locally
109103
'url' => 'http://localhost:3000', // url of the vite dev server
110104
],
111-
'forceProductionMode' => false, // or true to always serve build assets
112-
'plugin' => false, // or string 'MyPlugin' to serve plugin build assets
113-
'productionHint' => 'vprod', // can be a true-ish cookie or url-param to serve build assets without changing the forceProductionMode config
114-
'viewBlocks' => [
115-
'css' => 'css', // name of the css view block
116-
'script' => 'script', // name of the script view block
105+
'builds' => [
106+
[
107+
'plugin' => null, // the plugin name or null if it doesn't exist. Default: null
108+
'outputDirectory' => 'build', // the output directory relative to `webroot`. Default: 'build'
109+
'manifest' => 'build' . DS . '.vite' . DS . 'manifest.json', // the relative path to the manifest file. Default: 'build' . DS . '.vite' . DS . 'manifest.json'
110+
'environment' => \ViteHelper\Enum\Environment::PRODUCTION, // the forced environment, all files what 'falls' in this manifest file will be rendered this way. Default: the globally set environment
111+
],
117112
],
118113
],
119114
```
120115

121-
You can override the defaults in your `app.php`, `app_local.php`, or `app_vite.php`.
116+
You can override the defaults in your `app.php`, `app_local.php`, or `app_vite.php`, also you can override in
117+
`AppView.php` when you are loading the helper.
122118

123-
See the plugin's [app_vite.php](https://github.com/brandcom/cakephp-vite/blob/master/config/app_vite.php) for reference.
119+
```php
120+
$this->loadHelper('ViteHelper.ViteScripts', [
121+
// ...your config goes here
122+
]);
123+
```
124124

125-
Example:
125+
Since every build option has a default value:
126126

127127
```php
128-
return [
129-
'ViteHelper' => [
130-
'forceProductionMode' => 1,
131-
'development' => [
132-
'hostNeedles' => ['.dev'], // if you don't use one of the defaults
133-
'url' => 'https://192.168.0.88:3000',
134-
],
128+
'ViteHelper' => [
129+
'environment' => \ViteHelper\Enum\Environment::DEVELOPMENT, // available options PRODUCTION, DEVELOPMENT, FROM_DETECTOR
130+
'development' => [
131+
'url' => 'http://localhost:3000', // url of the vite dev server
132+
],
133+
'builds' => [
134+
[],
135+
['plugin' => 'MyAwesomePlugin', 'environment' => 'prod']
135136
],
136-
];
137+
],
137138
```
138139

139-
## Helper method usage with options
140+
These are valid builds. Assets from `MyAwesomePlugin` will be loaded like in production, the assets from root in development mode.
140141

141-
You can pass an `$options` array to override config or to completely skip the necessity to have a ViteHelper config.
142142

143-
The options are mostly the same for `::script()` and `::css()`.
143+
## Environment
144144

145-
### Example
145+
The plugin MUST accurately determine whether you are in development or production mode. You must explicitly set in the
146+
config that you are in either `\ViteHelper\Enum\Environment::PRODUCTION` or `\ViteHelper\Enum\Environment::DEVELOPMENT`.
147+
To enhance the flexibility of the plugin, you can utilize `\ViteHelper\Enum\Environment::FROM_DETECTOR`. This setting
148+
will employ a [detector](https://book.cakephp.org/5/en/controllers/request-response.html#Cake\Http\ServerRequest::is)
149+
to automatically detect the environment.
146150

147151
```php
148-
$this->ViteScripts->script([
149-
150-
// this would append both the scripts and the css to a block named 'myCustomBlock'
151-
// don't forget to use the block through $this->fetch('myCustomBlock')
152-
'block' => 'myCustomBlock',
153-
'cssBlock' => 'myCustomBlock', // for ::script() only – if you use css imports inside js.
152+
$this->request->addDetector(
153+
\ViteHelper\View\Helper\ViteScriptsHelper::VITESCRIPT_DETECTOR_NAME,
154+
function ($serverRequest) {
155+
// your logic goes here
156+
// return true for prod, false for dev
157+
}
158+
);
159+
```
154160

155-
// files that are entry files during development and that should be served during production
156-
'files' => [
157-
'webroot_src/main.ts',
158-
],
161+
In the development mode the plugins adds the necessary tags for development, in production this isn't happening.
159162

160-
// "devEntries" is like "files". If you set "files", it will override both "devEntries" and "prodFilters"
161-
'devEntries' => ['webroot_src/main.ts']
163+
## Helper method usage with options
162164

163-
// "prodFilter" filters the entry files. Useful for code-splitting if you don't use dynamic imports
164-
'prodFilter' => 'webroot_src/main.ts' // as string if there's only one option
165-
'prodFilter' => 'main.ts' // also works - only looks for parts of the string
166-
'prodFilter' => ['main.ts'] // as array - same as above with multiple files
167-
'prodFilter' => function (ManifestRecord $record) { /* do something with the record and return true or false */ }
168-
]);
169-
```
165+
The options are the same for `::script()` and `::css()`.
170166

171-
**Note:** You need to set `devEntries` when running the dev server. They have to either be set in the config or
172-
through the helper method. In contrast, you only need `files` or `prodFilter` if you are interested in php-side
173-
code-splitting and don't use dynamic imports in js.
167+
### Example
174168

175-
It depends on your project and use case how you define entries. If you don't use `prodFilter` or `files`, the plugin
176-
will serve all your entry files which might just be the case you want. So don't overconfigure it ;)
169+
```php
170+
$this->ViteScripts->script(
171+
files: ['resource/file1.js', 'resource/file2.js'], // Files as array/file as string
172+
block: null, // name of the view block to render the scripts in. Default: null
173+
plugin: null, // Plugin's name. Default: null
174+
175+
// Filter for environment. Default: null (in case of null the file(s) will be rendered both on prod and dev)
176+
// possible values: \ViteHelper\Enum\Environment::PRODUCTION, \ViteHelper\Enum\Environment::DEVELOPMENT, null
177+
environment: null,
178+
);
179+
```
177180

178-
## Opt out of global config + Plugin development
181+
## Performance
179182

180-
You can use the helper methods with multiple configurations through the `$config` argument.
183+
In production, it's possible that the manifest.json file is too large. If the default render mode is set to `AUTO`,
184+
every `::script()` and `::css()` call automatically and instantly adds the HTML tag to the block. You can disable this
185+
feature by setting render mode `MANUAL`.
181186

182-
> **New in version 2.3:** You can pass a config key instead of a config instance to the helper. The default config key
183-
> is `ViteHelper`.
187+
```php
188+
$this->loadHelper('ViteHelper.ViteScripts', [
189+
'render_mode' => \ViteHelper\Enum\RenderMode::MANUAL
190+
]);
191+
```
184192

185-
This might be useful when using plugin scripts or when developing plugins:
193+
In your php-layout, right before the `viewBlocks` you should manually call the `::render()` method or dispatch
194+
the `Vite.render` event.
186195

187196
```php
188-
<?php $this->ViteScripts->pluginScript('MyPlugin', devMode: true, config: 'MyPlugin.ViteConfig'); ?>
197+
$this->ViteScripts->script('resource/myscript1.js');
198+
$this->ViteScripts->script('resource/myscript2.js');
199+
// ... + a lot of script
200+
$this->ViteScripts->script('resource/myscriptN.js');
201+
$this->ViteScripts->render();
202+
<?= $this->fetch('css') ?>
189203
```
204+
or
190205

191-
The example above uses a convenience method to load plugin scripts for `MyPlugin`. DevMode is enabled and the helper
192-
will use a CakePHP config under the key `MyPlugin.ViteConfig`. In this way, you can scope your App's and your plugin's
193-
config.
194-
195-
It is assumed that the `manifest.json` is available directly in your plugin's `webroot`. If this is not the case, you
196-
should define the absolute path throuh the `build.manifest` config option.
206+
```php
207+
$this->ViteScripts->script('resource/myscript1.js');
208+
$this->ViteScripts->script('resource/myscript2.js');
209+
// ... + a lot of script
210+
$this->ViteScripts->script('resource/myscriptN.js');
211+
// dispatch 'Vite.render' event
212+
$this->getEventManager()->dispatch('Vite.render');
213+
<?= $this->fetch('css') ?>
214+
```
197215

198216
## Vite JS bundler / Dev server
199217

@@ -215,9 +233,9 @@ yarn add -D @vitejs/plugin-legacy
215233
### Configuration
216234

217235
After installing, you will need to refactor the files a bit to make sense of it in a php project. The default config of
218-
this plugin assumes that you put your js, ts, scss etc. in `/webroot_src`.
236+
this plugin assumes that you put your js, ts, scss etc. in `/resources`.
219237

220-
The build files will end up in `/webroot/assets` by default. Your `vite.config.js or *.ts` file for vite stays in the
238+
The build files will end up in `/webroot/build` by default. Your `vite.config.js or *.ts` file for vite stays in the
221239
project root.
222240

223241
> Wanted: Examples for vite/plugin configs and directory structures. Feel free to contribute with a PR to show how your

‎composer.json‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@
44
"type": "cakephp-plugin",
55
"license": "MIT",
66
"require": {
7-
"php": ">=8.1",
7+
"php": ">=8.3",
88
"cakephp/cakephp": "^5.0"
99
},
1010
"require-dev": {
@@ -33,8 +33,8 @@
3333
},
3434
"scripts": {
3535
"test": "phpunit",
36-
"cs-check": "phpcs --colors --parallel=16 -p src/",
37-
"cs-fix": "phpcbf --colors --parallel=16 -p src/",
36+
"cs-check": "phpcs --colors -p src/",
37+
"cs-fix": "phpcbf --colors -p src/",
3838
"stan": "phpstan analyse",
3939
"stan-setup": "cp composer.json composer.backup && composer require --dev phpstan/phpstan:^1.7.0 && mv composer.backup composer.json",
4040
"lowest-setup": "composer update --prefer-lowest --prefer-stable --prefer-dist --no-interaction && cp composer.json composer.backup && composer require --dev dereuromark/composer-prefer-lowest && mv composer.backup composer.json"

‎config/app_vite.php‎

Lines changed: 14 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -1,25 +1,23 @@
11
<?php
22

3-
use \ViteHelper\Utilities\ConfigDefaults;
4-
53
return [
64
'ViteHelper' => [
7-
'build' => [
8-
'outDirectory' => ConfigDefaults::BUILD_OUT_DIRECTORY,
9-
'manifest' => ConfigDefaults::BUILD_MANIFEST,
10-
],
5+
// the running environment
6+
'environment' => \ViteHelper\Enum\Environment::PRODUCTION,
7+
// development settings
118
'development' => [
12-
'scriptEntries' => ConfigDefaults::DEVELOPMENT_SCRIPT_ENTRIES,
13-
'styleEntries' => ConfigDefaults::DEVELOPMENT_STYLE_ENTRIES,
14-
'hostNeedles' => ConfigDefaults::DEVELOPMENT_HOST_NEEDLES,
15-
'url' => ConfigDefaults::DEVELOPMENT_URL,
9+
'url' => 'http://localhost:3000',
1610
],
17-
'forceProductionMode' => ConfigDefaults::FORCE_PRODUCTION_MODE,
18-
'plugin' => false,
19-
'productionHint' => ConfigDefaults::PRODUCTION_HINT,
20-
'viewBlocks' => [
21-
'css' => ConfigDefaults::VIEW_BLOCK_CSS,
22-
'script' => ConfigDefaults::VIEW_BLOCK_SCRIPT,
11+
// list of builds
12+
'builds' => [
13+
[
14+
// the plugin name or null if it doesn't exist
15+
'plugin' => null,
16+
// the output directory relative to `webroot`
17+
'outputDirectory' => 'build',
18+
// the relative path to the manifest file
19+
'manifest' => 'build' . DS . '.vite' . DS . 'manifest.json',
20+
],
2321
],
2422
],
2523
];

‎etc/vite.config.ts.example‎

Lines changed: 13 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,8 @@ import basicSsl from '@vitejs/plugin-basic-ssl'
55

66
// https://vitejs.dev/config/
77
export default defineConfig({
8+
root: '',
9+
publicDir: 'resources/assets',
810
plugins: [
911
basicSsl(),
1012
vue(),
@@ -26,23 +28,28 @@ export default defineConfig({
2628
protocol: 'wss',
2729
},
2830
watch: {
29-
ignored: [/bin/, /config/, /plugins/, /resources/, /tests/, /vendor/, /logs/, /tmp/],
30-
depth: 5,
31+
ignored: [/bin/, /config/, /plugins/, /tests/, /vendor/, /logs/, /tmp/],
32+
depth: 15,
3133
}
3234
},
3335
build: {
3436
emptyOutDir: true,
3537
outDir: './webroot/build',
36-
assetsDir: 'assets',
38+
assetsDir: './assets',
3739
manifest: true,
3840
rollupOptions: {
3941
input: [
40-
'./webroot_src/js/main.js',
41-
'./webroot_src/js/timetables.js',
42-
'./webroot_src/scss/style.scss',
42+
'./resources/js/main.js',
43+
'./resources/js/timetables.js',
44+
'./resources/scss/style.scss',
4345
],
4446
output: {
4547
entryFileNames: '[name].[hash].min.js',
48+
manualChunks(id) {
49+
if (id.includes('node_modules')) {
50+
return id.toString().split('node_modules/')[1].split('/')[0].toString();
51+
}
52+
}
4653
}
4754
}
4855
},

0 commit comments

Comments
 (0)