{"id":19095099,"url":"https://github.com/shopsys/plugin-interface","last_synced_at":"2025-04-30T14:09:27.329Z","repository":{"id":45642973,"uuid":"99080031","full_name":"shopsys/plugin-interface","owner":"shopsys","description":"[READ-ONLY] Package of interfaces providing compatibility between Shopsys Platform and plugins","archived":false,"fork":false,"pushed_at":"2025-04-15T14:34:47.000Z","size":49446,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":8,"default_branch":"17.0","last_synced_at":"2025-04-19T03:33:55.474Z","etag":null,"topics":["plugin","plugin-interface","shopsys-framework","shopsys-platform","ssfw"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/shopsys.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-08-02T06:22:33.000Z","updated_at":"2024-12-30T11:37:32.000Z","dependencies_parsed_at":"2024-04-17T11:51:18.118Z","dependency_job_id":"e3c117de-b3bb-4677-b21f-d2314998213a","html_url":"https://github.com/shopsys/plugin-interface","commit_stats":null,"previous_names":[],"tags_count":54,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shopsys%2Fplugin-interface","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shopsys%2Fplugin-interface/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shopsys%2Fplugin-interface/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shopsys%2Fplugin-interface/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/shopsys","download_url":"https://codeload.github.com/shopsys/plugin-interface/tar.gz/refs/heads/17.0","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251716908,"owners_count":21632203,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["plugin","plugin-interface","shopsys-framework","shopsys-platform","ssfw"],"created_at":"2024-11-09T03:32:45.257Z","updated_at":"2025-04-30T14:09:27.318Z","avatar_url":"https://github.com/shopsys.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Shopsys Plugin Interface\n\n[![Downloads](https://img.shields.io/packagist/dt/shopsys/plugin-interface.svg)](https://packagist.org/packages/shopsys/plugin-interface)\n\nPackage of interfaces providing compatibility between [Shopsys Platform](https://www.shopsys-framework.com) and plugins.\n\nThis repository is maintained by [shopsys/shopsys] monorepo, information about changes is in [monorepo CHANGELOG.md](https://github.com/shopsys/shopsys/blob/master/CHANGELOG.md).\n\n## Features\n\nThis package contains interfaces responsible for general functionality usable in almost any plugin.\nFor specific functionality, such as generating product feeds, there are [separate repositories](https://github.com/search?q=topic%3Aplugin-interface+org%3Ashopsys\u0026type=Repositories).\n\n#### Example\n\nFor example usage see the `AcmeProductCrudExtension` in the CRUD extension section below.\n\n### Storing data\n\nBest way to store your plugin data is to use Doctrine entities.\nCreate a folder (e.g. `src/Entity`) in your plugin and put your entities there.\nThen you need to create `DoctrineOrmMappingPass` and add it as `CompilerPass` in your `YourBundleNameBundle` class. This can be done like this:\n\n```php\n// vendor/your-bundle-name-bundle/src/YourBundleNameBundle.php\n\n// ...\n\n    /**\n     * @inheritdoc\n     */\n    public function build(ContainerBuilder $container) {\n        parent::build($container);\n\n        $container-\u003eaddCompilerPass(\n            DoctrineOrmMappingsPass::createAnnotationMappingDriver(\n                [$this-\u003egetNamespace() . '\\Entity'],\n                [$this-\u003egetPath() . '/Entity']\n            )\n        );\n    }\n\n// ...\n\n```\n\nThis tells Doctrine where to look for your entities. Now you can create `Repository` and manage your data as you are used to.\n\n### CRUD extension\n\nSometimes your plugin needs some extra information to be included in an entity, for example, you need to track the weight of products.\nThis can be solved by extending the entity CRUD model with your custom sub-form.\n\nTo do so you should implement [`PluginCrudExtensionInterface`](./src/PluginCrudExtensionInterface.php) and [tag the service in a DI container](http://symfony.com/doc/current/service_container/tags.html) with `shopsys.crud_extension` tag.\nThe tag should have a `type` attribute defining which CRUD model should be extended (eg. `\"product\"`).\n\nEach form extension has its label, form type and methods for managing the form data.\n\n#### Example\n\n```yaml\nservices:\n    acme.acme_product_crud_extension:\n        class: AcmePlugin\\AcmeProductCrudExtension\n        tags:\n            - { name: shopsys.crud_extension, type: product }\n\n    acme.acme_data_form_type:\n        class: AcmePlugin\\AcmeProductFormType\n        tags:\n            - { name: form.type }\n```\n\n```php\n// ...\nclass AcmeProductCrudExtension implements PluginCrudExtensionInterface\n{\n    private $acmeProductFacade;\n\n    public function __construct(AcmeProductFacade $acmeProductFacade) {\n        $this-\u003eacmeProductFacade = $acmeProductFacade;\n    }\n\n    public function getFormTypeClass()\n    {\n        return AcmeProductFormType::class;\n    }\n\n    public function getFormLabel()\n    {\n        return 'ACME data';\n    }\n\n    public function getData($productId)\n    {\n        $acmeProduct = $this-\u003eacmeProductFacade-\u003efindByProductId($productId);\n\n        $pluginData = [\n            'attribute' =\u003e $acmeProduct-\u003egetAttribute(),\n        ];\n\n        return $pluginData;\n    }\n\n    public function saveData($productId, $data)\n    {\n        $acmeProductData = new AcmeProductData();\n        $acmeProductData-\u003eattribute = $data['attribute'];\n\n        $this-\u003eacmeProductFacade-\u003esave($productId, $acmeProductData);\n    }\n\n    public function removeData($productId)\n    {\n        $this-\u003eacmeProductFacade-\u003eremove($productId);\n    }\n}\n```\n\n![ACME CRUD extension example](./docs/images/crud_extension_example.png)\n\n## Demo Data\n\nIn order to enable easy testing or to demonstrate usage of your plugin, you might want to provide demonstrational data with it.\nIn that case, you should implement [`PluginDataFixtureInterface`](./src/PluginDataFixtureInterface.php) that will take care of loading demonstrational data into the core.\n\nAll you got to do is to implement `PluginDataFixtureInterface::load()` method and [tag the service in a DI container](http://symfony.com/doc/current/service_container/tags.html) with `shopsys.data_fixture` tag.\n\n#### Example\n\n```yaml\nservices:\n    acme.acme_bundle.data_fixture:\n        class: AcmePlugin\\AcmeDataFixture\n        tags:\n            - { name: shopsys.data_fixture }\n```\n\n```php\nclass AcmeDataFixture implements PluginDataFixtureInterface\n{\n    private $acmeProductFacade;\n\n    public function __construct(AcmeProductFacade $acmeProductFacade) {\n        $this-\u003eacmeProductFacade = $acmeProductFacade;\n    }\n\n    public function load() {\n        $firstAcmeProductData = new AcmeProductData();\n        $firstAcmeProductData-\u003eenableWeightCalculation = true;\n        $firstAcmeProductData-\u003eweight = 42;\n        $firstAcmeProductData-\u003edomainId = 1;\n\n        $this-\u003eacmeProductFacade-\u003esave($firstAcmeProductData);\n\n        $secondAcmeProductData = new AcmeProductData();\n        $secondAcmeProductData-\u003eenableWeightCalculation = false;\n        $secondAcmeProductData-\u003eweight = null;\n        $secondAcmeProductData-\u003edomainId = 2;\n\n        $this-\u003eacmeProductFacade-\u003esave($secondAcmeProductData);\n    }\n\n}\n```\n\n## CRON modules\n\nWhen your plugin needs to execute some task periodically, for example downloading currency exchange rates every six hours, you can use a CRON module.\n\nThere are 2 types of CRON module interfaces:\n\n- [`SimpleCronModuleInterface`](./src/Cron/SimpleCronModuleInterface.php)\n    - for short tasks that do not take too long to execute\n- [`IteratedCronModuleInterface`](./src/Cron/IteratedCronModuleInterface.php)\n    - for long-running tasks that can be divided into smaller parts\n    - if the module takes too long to run it will be suspended and will be woken up and re-run during the next opportunity\n\nYou can implement either one of these interfaces and [tag the service in a DI container](http://symfony.com/doc/current/service_container/tags.html) with `shopsys.cron` tag.\n\nCRON modules are started automatically every time the current system time matches the specified mask in the tag attributes `hours` and `minutes`.\n\n### Example\n\n```yaml\nacme.data_download_cron_module:\n    class: AcmePlugin\\AcmeDataDownloadCronModule\n    tags:\n        - { name: shopsys.cron, hours: '*/6', minutes: '0' }\n```\n\n```php\n// ...\nclass AcmeDataDownloadCronModule implements SimpleCronModuleInterface\n{\n    /**\n     * @var \\Symfony\\Bridge\\Monolog\\Logger\n     */\n    private $logger;\n\n    public function setLogger(Logger $logger)\n    {\n        $this-\u003elogger = $logger;\n    }\n\n    public function run()\n    {\n        $data = $this-\u003edownloadData();\n        $this-\u003esaveData($data);\n\n        $this-\u003elogger-\u003einfo(sprintf('Downloaded %d new records.', count($data)));\n    }\n\n    // ...\n}\n```\n\n## How to implement a plugin\n\nPlugins are implemented in a form of a [Symfony bundle](http://symfony.com/doc/current/bundles.html).\nFor tips on how to write a new bundle see [Best Practices for Reusable Bundles](https://symfony.com/doc/current/bundles/best_practices.html).\n\n## Contributing\n\nThank you for your contributions to Shopsys Plugin Interface package.\nTogether we are making Shopsys Platform better.\n\nThis repository is READ-ONLY.\nIf you want to [report issues](https://github.com/shopsys/shopsys/issues/new) and/or send [pull requests](https://github.com/shopsys/shopsys/compare),\nplease use the main [Shopsys repository](https://github.com/shopsys/shopsys).\n\nPlease, check our [Contribution Guide](https://github.com/shopsys/shopsys/blob/master/CONTRIBUTING.md) before contributing.\n\n## Support\n\nWhat to do when you are in troubles or need some help?\nThe best way is to join our [Slack](https://join.slack.com/t/shopsysframework/shared_invite/zt-11wx9au4g-e5pXei73UJydHRQ7nVApAQ).\n\nIf you want to [report issues](https://github.com/shopsys/shopsys/issues/new), please use the main [Shopsys repository](https://github.com/shopsys/shopsys).\n\n[shopsys/shopsys]: (https://github.com/shopsys/shopsys)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshopsys%2Fplugin-interface","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fshopsys%2Fplugin-interface","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshopsys%2Fplugin-interface/lists"}