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/bundle_github_structure.png b/docs/administration/img/bundle_github_structure.png new file mode 100644 index 0000000000..36c22584f4 Binary files /dev/null and b/docs/administration/img/bundle_github_structure.png differ diff --git a/docs/administration/img/bundle_github_template.png b/docs/administration/img/bundle_github_template.png new file mode 100644 index 0000000000..5b8cccd779 Binary files /dev/null and b/docs/administration/img/bundle_github_template.png differ diff --git a/docs/administration/img/bundle_page_block.png b/docs/administration/img/bundle_page_block.png new file mode 100644 index 0000000000..afb9399ffa Binary files /dev/null and b/docs/administration/img/bundle_page_block.png differ diff --git a/docs/administration/img/new_tag.png b/docs/administration/img/new_tag.png new file mode 100644 index 0000000000..f029fe3981 Binary files /dev/null and b/docs/administration/img/new_tag.png differ diff --git a/docs/administration/img/packagist_submit.png b/docs/administration/img/packagist_submit.png new file mode 100644 index 0000000000..a5b22c15ae Binary files /dev/null and b/docs/administration/img/packagist_submit.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/bundle_extension/create_bundle.md b/docs/administration/project_organization/bundle_extension/create_bundle.md new file mode 100644 index 0000000000..0bca125795 --- /dev/null +++ b/docs/administration/project_organization/bundle_extension/create_bundle.md @@ -0,0 +1,262 @@ +--- +description: Create a bundle extension for Ibexa DXP. +--- + +# Create bundle + +A bundle is a reusable [[= product_name =]] extension that can be integrated. +To ensure full compatibility, follow the structure specifications described in the +[package structure](package_structure.md/#package-and-bundle-structure-and-namespaces) section. + +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. + +You can also 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 +``` + +## Create bundle with GitHub template + +1\. Go to the [[= product_name_base =]] [GitHub repository](https://github.com/ibexa/bundle-template). + +2\. In the upper-right corner, click the **Use this template** button, and select **Create a new repository**. + +3\. Provide repository name. Optionally, you can add description for the bundle. + +Next, click **Create repository**. + +![GitHub template](bundle_github_template.png) + +Once the repository is created, a workflow starts and generates the bundle structure. + +Vendor namespace is generated from the orgnization 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 and 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). + +## Build page block + +This section presents an example of how to create an extension that adds a new page block to Page Builder. + +1\. In `composer.json` add the Page Builder depency to be able to create a page block: + +```json + "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\. Page Builder isn't an open-source package, so to be able to use this dependency, add `repositories`: + +```json +"repositories": { + "ibexa": { + "type": "composer", + "url": "https://updates.ibexa.co" + } + } +``` + +3\. Next, run the following command to fetch the Page Builder dependency: + +```bash + composer update +``` + +For more information, see [bundles documentation](../../../administration/project_organization/bundles.md). + + +### Create bundle example + +!!! note + + Make sure you follow naming convention to ensure clarity. + + +### Define block + +Define specific settings for the page block bundle. Files should follow the Symfony configuration convention. Define various aspects of the bundle, include services, parameters, routess, and security. + +To define a page block, in the `prepend.yaml` file, add the following page block configuration: + +```yaml +ibexa_fieldtype_page: + blocks: + currency_exchange: + name: Currency exchange + thumbnail: /assets/images/blocks/random_block.svg#random + views: + default: + template: '@ibexadesign/blocks/currency_exchange/default.html.twig' + name: Currency exchange block + attributes: + amount: + type: integer + name: Amount + base_currency: + type: select + name: Base currency + options: + choices: + 'US Dollar': USD + 'EURO': EUR + 'Polish Zloty': PLN +``` +This file contains all configuration provided for 3rd party extension packages. + +### Implement view + +Create a view template that you indicated in the configuration. +In the `src`, add the `default.html.twig` file with the script provided by [Currency rate](https://currencyrate.today/exchangerates-widget): + +```html+twig + +
+``` + +Next, commit all changes to the GitHub. + +### Continuous integration + +To ensure quality requirements of your code in the newly created bundle, run: + +- `composer php cs fixer` +- `composer tests` + +Before releasing the newly created bundle, ensure your source meets quality requirements by running: +- run composer php cs fixer +- run composer test 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 +- unit tests + +## License and readme + +Before you publish the bundle, choose the license type and modify the readme file according to your needs. diff --git a/docs/administration/project_organization/bundle_extension/install_package.md b/docs/administration/project_organization/bundle_extension/install_package.md new file mode 100644 index 0000000000..1183be9d3f --- /dev/null +++ b/docs/administration/project_organization/bundle_extension/install_package.md @@ -0,0 +1,60 @@ +--- +description: Install created bundle extension into Ibexa DXP. +--- + +# Install bundle + +## Add repository to composer + + +To be able to install the bundle in your [[= product_name_base =]] project, 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" + } + } +``` + +## Install bundle into application + +On your [[= product_name_base =]] project root run: + +```bash +composer require acme/currency-exchange-rate:dev-main +``` + +!!! 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 + +Go to Page Builder edit mode. The Currency exchange block should be visible and available in the **Elements** panel. + +![Currency exchange page block](bundle_page_block.png) diff --git a/docs/resources/contributing/package_structure.md b/docs/administration/project_organization/bundle_extension/package_structure.md similarity index 65% rename from docs/resources/contributing/package_structure.md rename to docs/administration/project_organization/bundle_extension/package_structure.md index 30fe79ef10..4019c9ce9c 100644 --- a/docs/resources/contributing/package_structure.md +++ b/docs/administration/project_organization/bundle_extension/package_structure.md @@ -4,51 +4,44 @@ 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\