diff --git a/.gitignore b/.gitignore index bce609c564e768ba413ac0b146e880bf5b70c8b2..e653421831c07c54884e0774e7f1126f204261d1 100644 --- a/.gitignore +++ b/.gitignore @@ -1,6 +1,16 @@ -/.cache/ -/site/ /.ahoy.l3d -/.env +/.cache/ /docs/diagrams/uml/out/ /docs/__pycache__/ +/.env +/.idea/.gitignore +/.idea/documentation.iml +/.idea/git_toolbox_prj.xml +/.idea/modules.xml +/.idea/php.xml +/.idea/php-test-framework.xml +/.idea/inspectionProfiles/Project_Default.xml +/.idea/symfony2.xml +/.idea/vcs.xml +.gitignore +/site/ diff --git a/docs/composer/plugin/d10-scaffold/index.md b/docs/composer/plugin/d10-scaffold/index.md new file mode 100644 index 0000000000000000000000000000000000000000..32599af2429400712c4296fde95be299958d4068 --- /dev/null +++ b/docs/composer/plugin/d10-scaffold/index.md @@ -0,0 +1,10 @@ +--- +title: Composer Plugin Drupal 10 Scaffold +repo: https://gitlab.lakedrops.com/composer/plugin/drupal-10-scaffold +issues: https://gitlab.lakedrops.com/composer/plugin/drupal-10-scaffold/-/issues +tags: +- composer +--- +# Drupal 10 Project Template Scaffold + +This is a composer plugin which is utilized by the [Drupal 10 Project Template](/composer/project/d10) project. A detailed documentation can be found there. diff --git a/docs/composer/plugin/d8-sass-theme/index.md b/docs/composer/plugin/d8-sass-theme/index.md deleted file mode 100644 index 3f517c0d821bfb6ccce19c34c174ab5b4811e3d1..0000000000000000000000000000000000000000 --- a/docs/composer/plugin/d8-sass-theme/index.md +++ /dev/null @@ -1,251 +0,0 @@ ---- -title: Composer Plugin Drupal 8 SASS Theme -repo: https://gitlab.lakedrops.com/composer/plugin/drupal-8-sass-theme -issues: https://gitlab.lakedrops.com/composer/plugin/drupal-8-sass-theme/-/issues -tags: -- composer ---- -A Drupal 8 theme template that works with SASS, Bower, Gulp and **any Drupal 8 base theme** you want to use. This template also has a self-update feature built in and you should never have to copy/paste anything when setting up a custom theme for a Drupal project in the future. - -# Usage - -## Basic installation - -By default, this template uses Bartik as the base theme and you can start using it in an existing Drupal project by calling: - -```bash -composer require lakedrops/theme-d8-sass -``` - -This will add this template as a dependency to your composer.json file and create a custom theme named `mytheme` with all the settings requiered to get started immediately. - -## Advanced installation - -### Define the theme name - -To define a specific theme name you should simply add the following section to your '.lakedrops.yml': - -```yaml -theme-d8-sass: - project_name: NAME_YOUR_THEME -``` - -It is best practice to add this configuration into the composer.json before you install the theme itself, otherwise you'll end up with two custom themes, one with the default name and a second one with your own theme name. - -### Define and configure the base theme - -To use a different base theme than Bartik you can add the following configuration to your composer.json: - -```yaml -theme-d8-sass: - base_theme: - name: bootstrap - package: drupal/bootstrap - starterkit: starterkits/sass - sasspath: scss - import: - - overrides -``` - -| Key | Default | Description | -| --- | --- | --- | -| name | bartik | The Drupal project name of the base theme. | -| package | | The composer package name with namespace and package name so that Composer is able to find the package in the current installation for additional resources like starterkit. This parameter is required if you want to use any of the following settings and you have to make sure that this package is included as a requirement for your project. | -| starterkit | | If the base theme comes with a starterkit you can specify the relative path within that project where to find it. | -| sasspath | | The created custom theme is always based on a subdirectory called `sass` for all the sass or scss code. If the starterkit of the base theme uses a different directory name, then specify that here so that we can copy the files from the correct place into our sass directory. | -| import | [] | If the starterkit comes with basic files that you should import, then you can provide a list of names that will then be imported automatically. | - -Note: if you're using bootstrap as your base theme, you will also have to add the bower assets for the Bootstrap library which is explained below. The same may apply for other base themes, you should always find their requirements in their own documentation. Feel free to notify us about configurations on other base themes and we'll be adding that into the documentation here as well. - -### Adding bower assets - -Either a base theme or your own theme development style may require some libraries that are provided by [Bower](https://bower.io/search/). To add one or more Bower assets to your theme, simply add a section like this to your composer.json: - -```yaml -theme-d8-sass: - bower_assets: - bootstrap-sass: - name: bootstrap - version: "~3.3.7" - fonts: - src: assets/fonts/bootstrap - sass: - src: assets/stylesheets - import: - - bootstrap - js: - src: assets/javascripts -``` - -In the above example `bootstrap-sass` in the package name from the bower package repository and it contains a dictionary of values with these options: - -| Key | Description | -| --- | --- | -| name | The name how to identify this asset in your own theme. | -| version | This value is optional and defaults to the `latest` if not provided. Note: if you're using global bower assets (see below), this value here is ignored. | -| fonts | A dictionary containing the source directory where to find the fonts of that package. Those fonts will be copied over into your custom theme. | -| sass | A dictionary containing the source directory where to find the sass file of that package and a list of sass files that will be imported by the sass compiler when required. Those sass file will **not** be copied to your custom theme, because they will only be required for compilation but not to deliver those files to the browser of your website visitors. | -| js | A dictionary containing the source directory where to find the javascript files of that package. Those javascript file will be copied over into your custom theme and included into the library that adds them to the sites when required. | - -A bower.json file will be created dynamically when composer is executed and bower will be executed automatically to install and update all required assets locally in your theme. - -### Add bower assets globally - -The previous chapter describes how to add bower assets to your custom theme and without doing anything else, they will be added locally to your theme by using bower to install and update them. - -If you either want to avoid that overhead of using Bower or if any of these assets will be used by multiple projects, then you could install them globally in the vendor directory of your Drupal project. This will be done by composer if you add the following settings to your composer.json in addition to the settings in the previous chapter: - -```json -{ - "repositories": [ - { - "type": "composer", - "url": "https://asset-packagist.org" - } - ], - "require": { - "bower-asset/bootstrap-sass": "~3.3.7" - } -} -``` - -Your custom theme will then just use the assets from the vendor directory rather than keeping them in a `bower_components` subdirectory of the theme. But you still need the `bower_assets` settings in the extra section as described above. - -#### Other Bower Assets - -A short list of bower assets that might be interesting to add them to your theme: - -##### Flat-UI - -```json -{ - "require": { - "bower-asset/flat-ui-sass": "~2.1.3" - } -} -``` - -```yaml -theme-d8-sass: - bower_assets: - flat-ui-sass: - name: flat-ui - fonts: - src: vendor/assets/fonts.flat-ui - sass: - src: vendor/assets/stylesheets - import: - - flat-ui - js: - src: vendor/assets/javascripts -``` - -##### FontAwesome - -```json -{ - "require": { - "bower-asset/fontawesome": "~4.7.0" - } -} -``` - -```yaml -theme-d8-sass: - bower_assets: - fontawesome: - name: fontawesome - fonts: - src: fonts - sass: - src: scss - import: - - font-awesome -``` - -##### Animate - -```json -{ - "require": { - "bower-asset/animate-sass": "~0.6.0" - } -} -``` - -```yaml -theme-d8-sass: - bower_assets: - animate-sass: - name: animate - sass: - src: '' - import: - - animate - modules: - - bounceIn -``` - -For the animate package you have an additional list called `modules` which contains a list of animation modules that you want to enable for your custom theme. - -## Add optional scripts - -The custom theme will be updated when ever you either run `composer install` or `composer update` on your project. However, sometime you may only want to update the theme without running composer on the full project and you can achieve that by adding some custom scripts to your composer.json file: - -```json -{ - "scripts": { - "drupal-theme-install": "LakeDrops\\Drupal8Theme\\SASS\\Plugin::init", - "drupal-theme-update": "LakeDrops\\Drupal8Theme\\SASS\\Plugin::update", - "drupal-theme-reset": "LakeDrops\\Drupal8Theme\\SASS\\Plugin::reset", - "drupal-theme-overwrite": "LakeDrops\\Drupal8Theme\\SASS\\Plugin::overwrite" - } -} -``` - -You don't need them all, just add those that make sense to your development workflow. To run any of those scripts simply call `composer drupal-theme-update` which will then run that script. - -The available scripts in this package are: - -| Name | Purpose | -| --- | --- | -| init | Create or update the theme with all its files and settings. Do not overwrite any custom files and finally run `npm` and/or `bower` if required. | -| update | Same as `init` just that npm and bower will be called in update mode rather than install mode. | -| reset | Same as `init` with a prior reset which will remove fonts and javascript files from previously installed bower assets in the theme. | -| overwrite | Same as `init` but it will also overwrite custom files. | - -## Updating - -Simply call `composer update` in the root of your project and the latest version of this plugin will be updated and the changed files will then be updated in your custom theme. No worries, the files that you edited in your theme and that are not core to this plugin, won't be overwritten, so you keep your own work easily. - -At the end of the update, `gulp default` will be executed which will update your fonts, javascript files and compile your Sass files into css. This is useful for deployment of Drupal sites which will make sure that the theme assets are always up to date. - -The sass compiler also knows a development and a production mode. It uses development mode by default and production mode when composer is run with the `--no-dev` command line argument, which is usually the case in production environments. - -# Using Gulp - -Go to your theme's directory and call `gulp` once to run all of the available pre-processing. This is the equivalent of calling `gulp default`. - -If Gulp is not installed globally then you need to call `node_modules/.bin/gulp` in all examples of this chapter. - -Gulp by default will run the tasks `fonts`, `js` and `css` which are described in detail below. - -## Gulp tasks - -### Fonts - -`gulp fonts` will copy all fonts from all configured bower assets into the fonts subdirectory of your custom theme. - -### Javascript - -`gulp js` will copy all javascript files from all configured bower assets into the js subdirectory of your custom theme. - -### CSS - -`gulp css` will compile your sass files into css once. When adding the argument `--env production` then the output will be optimized for production environments, otherwise the output will be optimized for development. - -`gulp watch` will start a process that monitors your sass directory and automatically calls the css compilation when ever one or more files have changed. - -# Examples - -This template is embedded in our [D8 Project Template](/composer/project/d8) and looking into the composer.json there shows you all the options in action. diff --git a/docs/composer/plugin/drupal-dev-environment/index.md b/docs/composer/plugin/drupal-dev-environment/index.md index 6042b469d497c774434bbac921e60c78e03e2356..0adf67afb1e8185a35d39fe2c40f4498e3467672 100644 --- a/docs/composer/plugin/drupal-dev-environment/index.md +++ b/docs/composer/plugin/drupal-dev-environment/index.md @@ -4,7 +4,22 @@ repo: https://gitlab.lakedrops.com/composer/plugin/drupal-development-environmen issues: https://gitlab.lakedrops.com/composer/plugin/drupal-development-environment/-/issues tags: - composer +- testing --- # Drupal Development Environment This composer plugin builds all necessary structures of a Drupal project for development. +It provides a massive amount of testing tools, which can be executed out of the box using +[Ahoy](../../plugin/ahoy/index.md): + +- [Dependency Analysis](../../../dev_tools/test.md#php-code-sniffer) +- [PHP Unit](../../../dev_tools/test.md#unitkernelfunctional-testing) +- [PHP Code Sniffer](../../../dev_tools/test.md#php-code-sniffer) +- [PHP PHPStan](../../../dev_tools/test.md#php-code-sniffer) +- [PHP Lint](../../../dev_tools/test.md#php-code-sniffer) +- [PHP LOC](../../../dev_tools/test.md#php-loc) +- [PHP Mess Detection](../../../dev_tools/test.md#php-mess-detection) +- [PHP Copy and Paste Detector](../../../dev_tools/test.md#php-code-sniffer) +- [PHP Metrics](../../../dev_tools/test.md#php-code-sniffer) +- [PHP Stylelint](../../../dev_tools/test.md#php-code-sniffer) +- [Eslint](../../../dev_tools/test.md#php-code-sniffer) diff --git a/docs/composer/plugin/drupal-environment/index.md b/docs/composer/plugin/drupal-environment/index.md index a681abcb1497aa84a499155d96363cc3673ddcb5..0a5ad7021c0ce52cef40975e8cb16a90023c75c7 100644 --- a/docs/composer/plugin/drupal-environment/index.md +++ b/docs/composer/plugin/drupal-environment/index.md @@ -9,7 +9,7 @@ tags: This composer plugin builds all necessary directory structures for a Drupal project once during initial project creation or installation. -This plugin is required by the `lakedrops/drupal-development-environment` plugin and for development environments there is nothing else you need to be doing. +This plugin is required by the [lakedrops/drupal-development-environment](../drupal-dev-environment/index.md) plugin and for development environments there is nothing else you need to be doing. However, if you want to use the mechanism also on other non-development stages to create all the directories and links for you, then you can add `lakedrops/drupal-environment` as a requirement also to the required section of the root project. When you then call `composer install --no-interaction --no-dev` it will also install this plugin and create the full structure required. diff --git a/docs/composer/project/d10/index.md b/docs/composer/project/d10/index.md index 4d5a48c3bcf67fbceff451b0a352ee1d24f48033..16935ab023a738949e93759fba6e7c60c35686f8 100644 --- a/docs/composer/project/d10/index.md +++ b/docs/composer/project/d10/index.md @@ -5,5 +5,56 @@ issues: https://gitlab.lakedrops.com/composer/project/drupal-10/-/issues tags: - composer --- +# Usage -TBD +## Preparation + +- [Install composer](https://getcomposer.org): `sudo wget https://getcomposer.org/composer.phar --output-document=/usr/local/bin/composer && sudo chmod +x /usr/local/bin/composer` +- Disable XDebug for CLI - optional: `sudo phpdismod -s cli xdebug` +- [Install Prestissimo](https://github.com/hirak/prestissimo) - optional: `sudo composer global require "hirak/prestissimo:^0.3"` + +## Create new project for local development + +```bash +composer create-project lakedrops/d9-project [DIRNAME] --no-interaction +cd [DIRNAME] +``` + +This will build the full structure and create a git repository which you can then use during the full live-cycle of that project. + +To install a new site with the included default configuration, use `drush site-install --existing-config` and you get a jump-start from that. + +## Deploy project to upstream stages + +For deployment, both initially and for later updates, follow this: + +``` +mkdir /PATH/TO/ROOT +cd /PATH/TO/ROOT +git clone YOUR-GIT-REPOSITORY . +composer install +``` + +## Adding new and updating existing components + +Edit the composer.json file accodring to your requirements and then run `composer update`. + +## Adding JS packages + +### CKEditor Codesnippet + +```bash +composer config repositories.codesnippet '{"type": "package","package": {"name": "ckeditorplugin/codesnippet","type": "drupal-library","version": "master","dist": {"type": "zip","url": "https://download.ckeditor.com/codesnippet/releases/codesnippet_4.7.3.zip","reference": "master"}}}' +composer require ckeditorplugin/codesnippet:master drupal/codesnippet +``` + +### Chosen + +```bash +composer config repositories.codesnippet '{"type": "package","package": {"name": "harvesthq/chosen","version": "1.8.2","type": "drupal-library","dist": {"url": "https://github.com/harvesthq/chosen/releases/download/v1.8.2/chosen_v1.8.2.zip","type": "zip"}}}' +composer require harvesthq/chosen +``` + +# Links + +[Using Composer to install Drupal packages through Drupal.org](https://www.drupal.org/node/2718229) diff --git a/docs/dev_tools/test.md b/docs/dev_tools/test.md index 9300f6f7270ebdcc3fc837b4eb36d53816769886..97598a6cee55000f3e382a90a2eb45a199d542b9 100644 --- a/docs/dev_tools/test.md +++ b/docs/dev_tools/test.md @@ -11,43 +11,44 @@ tags: This section describes everything we have to test our code from static code analysis to unit testing. -You also have to set up your environment with the tool [l3d](../docker/l3d/index.md). +You also have to set up your environment with the tool [l3d](../docker/l3d/index.md). The composer plugin +[Drupal Development Environment](../composer/plugin/drupal-dev-environment/index.md) does all the setup for you. ## Static Code Analysis We have several tools to perform static code analysis. -* PHP LOC * Code Sniffer +* PHP LOC * Mess Detection -### PHP LOC +### PHP Code Sniffer -PHP LOC prints several metrics about your code, like the average size of a class. +PHP Code Sniffer performs a static code analysis with a specific Drupal profile. It detects +code smells like static calls. -To execute PHP LOC on the console: +To execute PHP Code Sniffer on the console: ```l3d -a test phploc <file_ordirectory> +a test phpcs <file_ordirectory> ``` Whether it is a directory, it runs the analysis for everything under this directory recursively. -### PHP Code Sniffer +Whether it is a directory, it runs the analysis for everything under this directory +recursively. -PHP Code Sniffer performs a static code analysis with a specific Drupal profile. It detects -code smells like static calls. +### PHP LOC -To execute PHP Code Sniffer on the console: +PHP LOC prints several metrics about your code, like the average size of a class. + +To execute PHP LOC on the console: ```l3d -a test phpcs <file_ordirectory> +a test phploc <file_ordirectory> ``` -Whether it is a directory, it runs the analysis for everything under this directory -recursively. - ### PHP Mess Detection PHP Mess Detection is a more detailed analysis comparing to code sniffer. It diff --git a/mkdocs.yml b/mkdocs.yml index 27814103eb03462e798fd50171c3e15471c7b9d1..86f2440aba5cd15bcf6b4261fd4134c8e3092b1b 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -109,9 +109,9 @@ nav: - Ahoy: composer/plugin/ahoy/index.md - Behat for Drupal: composer/plugin/b4d/index.md - Docker for Drupal: composer/plugin/d4d/index.md - - Drupal 8 SASS Theme: composer/plugin/d8-sass-theme/index.md - Drupal 8 Scaffold: composer/plugin/d8-scaffold/index.md - Drupal 9 Scaffold: composer/plugin/d9-scaffold/index.md + - Drupal 10 Scaffold: composer/plugin/d10-scaffold/index.md - Dorgflow: composer/plugin/dorgflow/index.md - Drupal Development Environment: composer/plugin/drupal-dev-environment/index.md - Drupal Environment: composer/plugin/drupal-environment/index.md