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 }} +
CurrencyRate
+``` + +### 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\`) -| +-- 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) @@ -56,58 +69,76 @@ The `src/lib` directory and its corresponding `Ibexa\` namespace ar Examples: + + ```php namespace Ibexa\Search; ``` + + ```php 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 have the following 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 // ... ``` + + ### Contracts A package may introduce a namespace for contracts, to be consumed by first and third party packages and projects, which must be prefixed as: + + ```php namespace Ibexa\Contracts; ``` Examples: + + ```php namespace Ibexa\Contracts\Kernel; ``` + + ```php namespace Ibexa\Contracts\SiteFactory; ``` + + ```php namespace Ibexa\Contracts\Commerce\Shop; ``` @@ -115,5 +146,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/packages_and_bundles/upload_packagist.md b/docs/administration/project_organization/packages_and_bundles/upload_packagist.md new file mode 100644 index 0000000000..fe2397c55e --- /dev/null +++ b/docs/administration/project_organization/packages_and_bundles/upload_packagist.md @@ -0,0 +1,29 @@ +# Upload bundle to Packagist + +1\. Go to the Packagist website. Click submit. +1\. Provide the repository url to your package. + +1\. When you add a new feature, you need to create a tag. +In PHPStorm or other PHP IntelliJ editor, go to commits, Log and create a new tag. +Then a new version will be published on packagist. + +1\. Link repo with packagist. +Make sure your repository is set to public. +Each time you add a new feature to your bundle, you need to also add a new tag. +New version will be released on Packagist. + +1\. Click the **Check** button to verify the completeness of the bundle. + +In `composer.json` in the repositories + +```json + "repositories": [ + { + "type": "composer", + "url": "https://updates.ibexa.co" + } +``` + +Indicate the type for path +and url - bundle name +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 049bb4a864..85d8d554dc 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 + - Packages and bundles: + - Package structure: administration/project_organization/packages_and_bundles/package_structure.md + - Create bundle: administration/project_organization/packages_and_bundles/create_bundle.md + - Install bundle: administration/project_organization/packages_and_bundles/install_package.md + - Upload on Packagist: administration/project_organization/packages_and_bundles/upload_packagist.md - Admin panel: - Admin panel: administration/admin_panel/admin_panel.md - Users: administration/admin_panel/users_admin_panel.md @@ -755,9 +760,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