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 + +
CurrencyRate
+``` + +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\`) -| +-- contracts (`Ibexa\Contracts\`) -| +-- lib (`Ibexa\`) +|   +-- bundle (`Ibexa\Bundle\`) +|   +-- contracts (`Ibexa\Contracts\`) +|   +-- lib (`Ibexa\`) +-- tests -| +-- bundle (`Ibexa\Tests\Bundle\`) -| +-- integration (`Ibexa\Tests\Integration\`) -| +-- lib (`Ibexa\Tests\`) +|   +-- bundle (`Ibexa\Tests\Bundle\`) +|   +-- integration (`Ibexa\Tests\Integration\`) +|   +-- lib (`Ibexa\Tests\`) ``` -If a package does not contain some of the described parts, you can skip those directories. +If a package doesn't contain some of the described parts, you can skip those directories. ### Implementation (lib) @@ -66,26 +59,24 @@ namespace Ibexa\Commerce\Shop; ### Bundles -The bundle class definition in the `src/bundle` directory must be: +The bundle class definition in the `src/bundle` directory must follow the pattern: ```php namespace Ibexa\Bundle\; - +  class Ibexa[ProductGroup]Bundle // ... ``` Examples: - ```php namespace Ibexa\Bundle\Search; - +  class IbexaSearchBundle // ... ``` ```php namespace Ibexa\Bundle\Commerce\Shop; - class IbexaCommerceShopBundle // ... ``` @@ -115,5 +106,4 @@ namespace Ibexa\Contracts\Commerce\Shop; That namespace needs to be mapped to the `src/contracts` directory of a package. !!! note - Backward compatibility for interfaces and objects defined in the `Contracts` namespace is guaranteed. diff --git a/docs/administration/project_organization/bundle_extension/upload_packagist.md b/docs/administration/project_organization/bundle_extension/upload_packagist.md new file mode 100644 index 0000000000..9bd05258a3 --- /dev/null +++ b/docs/administration/project_organization/bundle_extension/upload_packagist.md @@ -0,0 +1,45 @@ +--- +description: Upload created bundle extension to Packagist. +--- + +# Upload bundle to Packagist + +The following section explains how to upload created bundle on the [packagist.org](https://packagist.org/) website. + +1\. Go to the Packagist website and click **Submit**. + +![Submit package](packagist_submit.png) + +2\. Provide the repository URL to your package, for example: + +`https://github.com/acme/example-3rd-party-extension` + +!!! note + When you add a new feature, you need to create a tag. +3\. To create a new tag, in GitHub, go to **Tags** section, and click **Create a new release**. + +![New tag](new_tag.png) + +4\. Link your bundle repository with Packagist. + +Make sure the repository is set to public. +Each time you add a new feature to your bundle, you need to also add a new tag. + +5\. Click the **Check** button to verify the bundle completeness. + +In `composer.json` in the `repositories` indicate the type and bundle URL: + +```json +"repositories": { + "ibexa": { + "type": "composer", + "url": "https://updates.ibexa.co" + }, + "acme/currency-exchange-rate":{ + "type": "vcs", + "url": "https://github.com/acmee/example-3rd-party-extension" + } + } +``` + +Any change in repository immediately affects the other bundle so you can see the changes. \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml index cc3b6d5386..40043a2e3d 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -90,6 +90,11 @@ nav: - Project organization: administration/project_organization/project_organization.md - Architecture: administration/project_organization/architecture.md - Bundles: administration/project_organization/bundles.md + - Bundle extension: + - Package structure: administration/project_organization/bundle_extension/package_structure.md + - Create bundle: administration/project_organization/bundle_extension/create_bundle.md + - Install bundle: administration/project_organization/bundle_extension/install_package.md + - Upload on Packagist: administration/project_organization/bundle_extension/upload_packagist.md - Admin panel: - Admin panel: administration/admin_panel/admin_panel.md - Users: administration/admin_panel/users_admin_panel.md @@ -756,9 +761,9 @@ nav: - Ibexa DXP PhpStorm plugin: resources/phpstorm_plugin.md - New in documentation: resources/new_in_doc.md - Contributing: + - Report and follow issues: resources/contributing/report_and_follow_issues.md - Contribute translations: resources/contributing/contribute_translations.md - - Package structure: resources/contributing/package_structure.md - Release notes: - Release notes: release_notes/release_notes.md - Ibexa DXP v4.5: release_notes/ibexa_dxp_v4.5.md diff --git a/plugins.yml b/plugins.yml index 69a6a42af9..8ed53a59cc 100644 --- a/plugins.yml +++ b/plugins.yml @@ -466,7 +466,7 @@ plugins: 'community_resources/phpstorm_plugin.md': 'resources/phpstorm_plugin.md' 'community_resources/report_follow_issues.md': 'resources/contributing/report_and_follow_issues.md' 'community_resources/translations.md': 'resources/contributing/contribute_translations.md' - 'community_resources/package_structure.md': 'resources/contributing/package_structure.md' + 'community_resources/package_structure.md': 'administration/project_organization/bundle_extension/package_structure.md' 'updating/update_ibexa_dxp.md': 'update_and_migration/update_ibexa_dxp.md' 'updating/from_1.x_2.x/update_from_1.x_2.x.md': 'update_and_migration/from_1.x_2.x/update_from_1.x_2.x.md'