diff --git a/docs/administration/img/bundle_generator.png b/docs/administration/img/bundle_generator.png new file mode 100644 index 0000000000..cf196a4d7c Binary files /dev/null and b/docs/administration/img/bundle_generator.png differ diff --git a/docs/administration/img/sys_info_composer_tab.png b/docs/administration/img/sys_info_composer_tab.png new file mode 100644 index 0000000000..d007c96332 Binary files /dev/null and b/docs/administration/img/sys_info_composer_tab.png differ diff --git a/docs/administration/project_organization/packages_and_bundles/create_bundle.md b/docs/administration/project_organization/packages_and_bundles/create_bundle.md new file mode 100644 index 0000000000..a3e46d9a0d --- /dev/null +++ b/docs/administration/project_organization/packages_and_bundles/create_bundle.md @@ -0,0 +1,316 @@ +--- +description: All code contributions to Ibexa DXP must follow package and bundle structure and namespace standards. +--- + +# Create bundle + +The following section explains the whole process from creating a bundle from scratch to uploading it on the [packagist.org](https://packagist.org/) website. + +A bundle is modular structure that contain related functionality and can be integrated into an application. +[Follows specific strucutre](package_structure.md/#package-and-bundle-structure-and-namespaces). + +The bundle extension described here is called `AcmeCurrencyExchangeRate` and enables a new page block which displays a currency exchange rate on your site. + +You can create a bundle skeleton in two simplified ways: + +- [using Ibexa bundle generator](#create-bundle-with-bundle-generator) +- [with GitHub template](#use-github-template) + +## Create bundle with bundle-generator + +[[= product_name_base =]] bundle generator is a Symfony Bundle generator for projects based on [[= product_name =]]. +It can work as a standalone application mode. +This section thoroughly explains how to create a bundle using generator as a stand-alone application. +You can use this skeleton as a basis for your extension project. +It's the easiest and recommended way. + +1\. Go to [Ibexa bundle generator](https://github.com/ibexa/bundle-generator){:target="\_blank"} and clone the repository. + +```bash +git clone git@github.com:ibexa/bundle-generator.git +``` +2\. Change to bundle generator directory. + +```bash +cd bundle-generator +``` + +3\. Install dependencies: + +```bash +composer install +``` + +4\. Run bundle generator: + +```bash +php bin/ibexa-bundle-generator currency-exchange-rate --skeleton-name=extension +``` + +5\. Adjust the bundle to your needs providing the following parameters. + The command runs with an interactive mode. + +- Package vendor name - acme +- Bundle vendor namespace - Acme +- Bundle name - CurrencyExchangeRate +- Skeleton name - acme-ee + +![Bundle generator](bundle_generator.png) + +This creates a bundle files structure in the `./target` directory. + +You can rename the target directory according to your needs. + +Or you can use a command with all available options: + + +```bash +php bin/ibexa-bundle-generator currency-exchange-rate currency-exchange-rate-dir --vendor-name=acme --vendor-namespace=ACME --bundle-name=CurrencyExchangeRate --skeleton-name=extension +``` + +## Use GitHub template + +https://github.com/ibexa/bundle-template + +Directory structure for AcmeCurrencyExchangeRate +podac url +button use template + + + + +Once the repository is created, a workflow starts which generates a bundle structure. +- Vendor namespace is generated from the orgnization name: github/github user name. +Package and bundle name inherits from repository name. + + + +### Bundle directory structure + +Generated bundle consists of the following structure: + +``` +. +├── LICENSE +├── README.md +├── composer.json +├── deptrac.yaml +├── package.json +├── phpstan.neon +├── phpunit.xml.dist +├── src +│ ├── bundle +│ │ ├── AcmeCurrencyExchangeRateBundle.php +│ │ ├── DependencyInjection +│ │ │ └── AcmeCurrencyExchangeRateExtension.php +│ │ └── Resources +│ │ ├── config +│ │ │ ├── prepend.yaml +│ │ │ ├── services +│ │ │ └── services.yaml +│ │ └── views +│ │ └── themes +│ │ ├── admin +│ │ └── standard +│ ├── contracts +│ └── lib +└── tests + ├── bundle + ├── integration + └── lib +``` +Where: + + +- LICENSE - a license file, GPL v2 by default +- README.md - a readme file with bundle description, its version and install instructions +- `composer.json` - a package definition +- `deptrac.yaml` - a tool for static code analysis for PHP, checks the coherence of package architecture, for more information see [deptrac](https://qossmic.github.io/deptrac/) documentation. +- `package.json` - frontend dependencies, for more information, see [about packages and modules](https://docs.npmjs.com/about-packages-and-modules). +- `phpstan.neon` - phpstan configuration, a tool for static code analysis for PHP, scans, and evaluates codebase to find errors, and bugs, for more information, see the [documentation](https://phpstan.org/user-guide/getting-started). +- `phpunit.xml.dist` - config for phpunit, unit and integration tests - see [documentation](https://phpunit.de/getting-started/phpunit-10.html). +- src and tests follow the base catalog structure, according to [package structure](https://phpunit.de/getting-started/phpunit-10.html) docs. + + +To fully use the possibilities of the bundle, get familiar with the structure: + +- `resources/` + - `config/` - contains configuration for the environment/ governs budle configuration + - `services/` - recommended place for services definition files + all services definitions must be split into separate files + - `prepend.yaml` - houses additional configuration for other extensions + - `views/` - handles the [design engine](../../../templating/design_engine/design_engine.md) +- `tests` - contains all tests for the bundle. For more information, see [continuous integration](#continuous-integration). + +### Add the dependencies to the composer.json + +1. In composer.json add the Page Builder depency to be able to create a page block. + +```json hl_lines="156" + "require": { + "php": "^7.4 || ^8.0", + "ibexa/core": "^4.5", + "ibexa/page-builder": "^4.5", + "symfony/config": "^5.4", + "symfony/dependency-injection": "^5.4", + "symfony/event-dispatcher": "^5.4", + "symfony/event-dispatcher-contracts": "^2.2", + "symfony/http-foundation": "^5.4", + "symfony/http-kernel": "^5.4", + "symfony/yaml": "^5.4", + "http-interop/http-factory-guzzle": "^1.2" + }, +``` +2. Run the following command: + +```bash + composer update +``` + +```json + "scripts-descriptions": { + "fix-cs": "Automatically fixes code style in all files", + "check-cs": "Run code style checker for all files", + "test": "Run automatic tests", + "phpstan": "Run static code analysis", + "deptrac": "Run Deptrac architecture testing" + }, +``` + +- `composer.json` - defines your project requirements, contains the following sections: + + - `php-cs-fixer` - defines method of verifying/checking code style, by default as internal package `for Ibexa style` + - `eslintrc` - a tool for static code analysis for JavaScript + + +For more information, see [bundles](../../../administration/project_organization/bundles.md) documentation. + + +### Create class + +!!! note + + Make sure you follow naming convention to ensure clarity. + +In the `/src` create a ACMECurrencyExchangeRateBundle class: + + +```php +var fm = "{{ base_currency }}"; +var to = "BTC,AUD,GBP,EUR,CNY,JPY,RUB"; +var tz = "timezone"; +var sz = "1x349"; +var lg = "en";var st = "primary"; +var cd = 0; +var am = {{ amount }} +
+``` + +### Continuous integration + +Before releasing the newly created bundle: +run php cs fixer +run unit tests + +[GitHub actions](https://docs.github.com/en/actions) + +To ensure delivery of working code, use CI/CD pipeline right from the GitHub repository. + +Best practices for testing your bundle encompas:: + +- supported Symfony versions +- supported PHP versions + + +### Continuous development + + +## License and readme + +Choose license type, modify readme doc. \ No newline at end of file diff --git a/docs/administration/project_organization/packages_and_bundles/install_package.md b/docs/administration/project_organization/packages_and_bundles/install_package.md new file mode 100644 index 0000000000..f13480cb4c --- /dev/null +++ b/docs/administration/project_organization/packages_and_bundles/install_package.md @@ -0,0 +1,74 @@ +# Install bundle + + + +## Add repository to composer + +To be able to install the bundle to your [[= product_name_base =]] project, first, update the requirements. + + +```json + "require": { + "php": ">=7.4", + "ext-ctype": "*", + "ext-iconv": "*", + "acme/video-editor": "dev-master", + "ibexa/commerce": "4.6.x-dev", + "ibexa/connector-seenthis": "^4.6@dev", +``` + + +Next, add the repository to the `composer.json`: + +```json hl_lines="17" + "repositories": { + "ibexa": { + "type": "composer", + "url": "https://updates.ibexa.co" + }, + "acme/currency-exchange-rate":{ + "type": "vcs", + "url": "file:///Users/justyna.koralewicz/example-3rd-party-extension" + } + } +``` + + +On your [[= product_name_base =]] root project run: + +```bash +composer require acme/currency-exchange-rate:dev-master +``` + +!!! note + + If your application uses Symfony Flex, the bundle is registered automatically after you install it. + + +Check whether the bundle is enabled, if not, you must enable it per environment in the `config/bundles.php` file: + + +```php +return [ + Symfony\Bundle\FrameworkBundle\FrameworkBundle::class => ['all' => true], + ... + Ibexa\Bundle\TestFixtures\IbexaTestFixturesBundle::class => ['all' => true], + ACME\Bundle\CurrencyExchangeRate\ACMECurrencyExchangeRateBundle::class => ['all' => true], +]; +``` + + +Next, clear the cache by runnig the following command: + +```bash +php bin/console cache:clear +``` + +The newly installed bundle should be visible in the **Composer** tab in **Admin** -> **System information**. + +![Installed bundles](sys_info_composer_tab.png) + + +## Add currency exchange page block + + diff --git a/docs/resources/contributing/package_structure.md b/docs/administration/project_organization/packages_and_bundles/package_structure.md similarity index 64% rename from docs/resources/contributing/package_structure.md rename to docs/administration/project_organization/packages_and_bundles/package_structure.md index 30fe79ef10..626a6835f8 100644 --- a/docs/resources/contributing/package_structure.md +++ b/docs/administration/project_organization/packages_and_bundles/package_structure.md @@ -4,51 +4,64 @@ description: All code contributions to Ibexa DXP must follow package and bundle # Package and bundle structure and namespaces -If you wish to contribute to [[= product_name =]] development, -you need to adhere to the package and bundle structure and namespace standards. +Bundle allows you to extend the system by adding new services, routes, controllers, and views, and extend functionality to fully customize your [[= product_name =]] application. +If you want to contribute to [[= product_name =]] development, you need to adhere to the package and bundle structure and namespace standards. -The following conventions apply to contributions to [[= product_name_base =]] core code, not to third party packages. +All conventions described here apply to contributions to [[= product_name_base =]] core code, not to third party packages. !!! note - New code needs to follow the rules outlined here. They are being applied progressively to existing code. + + ## Root PHP namespace Define [[= product_name =]] core PHP code in a namespace with the following prefix: + + ```php namespace Ibexa; ``` A package which groups some DXP features can use an additional prefix, for example: + + ```php namespace Ibexa\Commerce; ``` + + ```php namespace Ibexa\Personalization; ``` + + ## Packages -The general package directory structure and corresponding PHP namespace mapping are: +The general package directory structure and corresponding PHP namespace mappings are: + + ``` . +-- src -| +-- bundle (`Ibexa\Bundle\