[{"data":1,"prerenderedAt":28},["ShallowReactive",2],{"$f3dkanh4r5i7c7":3,"$f38h4rgfxzd3qv":21},{"content":4,"package":5,"version":20},"# Installation & Setup\n\nTo install this plugin, run the following [Composer](https:\u002F\u002Fgetcomposer.org\u002F) command:\n\n```bash\ncomposer require babdev\u002Fsylius-product-samples-plugin\n```\n\nThe plugin adds fields to the channel, product, and product variant models, so installing it is not only a matter of registering the bundle. The steps below cover a complete working install.\n\n## Register The Plugin\n\nFor an application using Symfony Flex the plugin should be automatically registered, but if not you will need to add it to your `config\u002Fbundles.php` file.\n\n```php\n\u003C?php\n\nreturn [\n    \u002F\u002F ...\n\n    BabDev\\SyliusProductSamplesPlugin\\BabDevSyliusProductSamplesPlugin::class => ['all' => true],\n];\n```\n\n## Import the Configuration\n\nIn your `config\u002Fpackages\u002F_sylius.yaml` file, import the plugin's application configuration to automatically configure its integrations with other bundles.\n\n```yaml\nimports:\n    - { resource: \"@BabDevSyliusProductSamplesPlugin\u002FResources\u002Fconfig\u002Fapp\u002Fconfig.yaml\" }\n```\n\nThis wires the product samples fields into the admin channel form. The storefront integrations are opt-in and are covered further down.\n\n## Extend the Models\n\nThe plugin needs three extra pieces of data:\n\n| Model            | Addition                                                                    |\n|------------------|-----------------------------------------------------------------------------|\n| `Channel`        | `maxSamplesPerOrder`, the per-order sample limit for that channel           |\n| `Product`        | `samplesActive`, whether the product offers samples                         |\n| `ProductVariant` | `sample` \u002F `sampleOf`, the one-to-one link between a variant and its sample |\n\nThe channel side is offered as an interface and a trait so your application is not forced into an inheritance chain it may already be using. The product and variant sides are concrete classes to extend.\n\nCreate the three classes in your application:\n\n```php\n\u003C?php\n\ndeclare(strict_types=1);\n\nnamespace App\\Entity\\Channel;\n\nuse BabDev\\SyliusProductSamplesPlugin\\Model\\ChannelInterface as ProductSamplesChannelInterface;\nuse BabDev\\SyliusProductSamplesPlugin\\Model\\ChannelTrait as ProductSamplesChannelTrait;\nuse Sylius\\Component\\Core\\Model\\Channel as BaseChannel;\n\nclass Channel extends BaseChannel implements ProductSamplesChannelInterface\n{\n    use ProductSamplesChannelTrait;\n}\n```\n\n```php\n\u003C?php\n\ndeclare(strict_types=1);\n\nnamespace App\\Entity\\Product;\n\nuse BabDev\\SyliusProductSamplesPlugin\\Model\\Product as BaseProduct;\n\nclass Product extends BaseProduct\n{\n}\n```\n\n```php\n\u003C?php\n\ndeclare(strict_types=1);\n\nnamespace App\\Entity\\Product;\n\nuse BabDev\\SyliusProductSamplesPlugin\\Model\\ProductVariant as BaseProductVariant;\n\nclass ProductVariant extends BaseProductVariant\n{\n}\n```\n\nIf your application already extends Sylius' `Product` and `ProductVariant`, change the class each one extends to the plugin's; the plugin's classes extend the Sylius ones.\n\nThen point the resource configuration at them in `config\u002Fpackages\u002F_sylius.yaml`:\n\n```yaml\nsylius_channel:\n    resources:\n        channel:\n            classes:\n                model: 'App\\Entity\\Channel\\Channel'\n\nsylius_product:\n    resources:\n        product:\n            classes:\n                model: 'App\\Entity\\Product\\Product'\n        product_variant:\n            classes:\n                model: 'App\\Entity\\Product\\ProductVariant'\n                repository: 'BabDev\\SyliusProductSamplesPlugin\\Doctrine\\ORM\\ProductVariantRepository'\n```\n\n::div{class=\"docs-note docs-note--tip\"}\n\u003Cstrong>The repository is not optional.\u003C\u002Fstrong> Sample variants are rows in the \u003Ccode>sylius_product_variant\u003C\u002Fcode> database table, so without the plugin's repository they show up alongside real variants in the admin product variant grid. The plugin's repository extends Sylius' own and adds a single \u003Ccode>sampleOf IS NULL\u003C\u002Fcode> condition to the grid queries. If your application already replaces the product variant repository, extend the plugin's class instead of Sylius'.\n::\n## Map the New Fields in Doctrine\n\nThe plugin ships no Doctrine mapping of its own, because the fields have to be mapped onto *your*\nclasses. Add the three mapping files below to your application's mapping directory, and register\nthat directory if it is not already:\n\n```yaml\n# config\u002Fpackages\u002Fdoctrine.yaml\ndoctrine:\n    orm:\n        mappings:\n            App:\n                type: xml\n                dir: '%kernel.project_dir%\u002Fconfig\u002Fdoctrine'\n                prefix: App\\Entity\n```\n\n`config\u002Fdoctrine\u002FChannel.orm.xml`:\n\n```xml\n\u003C?xml version=\"1.0\" encoding=\"UTF-8\"?>\n\n\u003Cdoctrine-mapping xmlns=\"http:\u002F\u002Fdoctrine-project.org\u002Fschemas\u002Form\u002Fdoctrine-mapping\"\n                  xmlns:xsi=\"http:\u002F\u002Fwww.w3.org\u002F2001\u002FXMLSchema-instance\"\n                  xsi:schemaLocation=\"http:\u002F\u002Fdoctrine-project.org\u002Fschemas\u002Form\u002Fdoctrine-mapping\n                                      http:\u002F\u002Fdoctrine-project.org\u002Fschemas\u002Form\u002Fdoctrine-mapping.xsd\">\n\n    \u003Cmapped-superclass name=\"App\\Entity\\Channel\\Channel\" table=\"sylius_channel\">\n\n        \u003Cfield name=\"maxSamplesPerOrder\" column=\"max_samples_per_order\" type=\"integer\" nullable=\"true\" \u002F>\n\n    \u003C\u002Fmapped-superclass>\n\n\u003C\u002Fdoctrine-mapping>\n```\n\n`config\u002Fdoctrine\u002FProduct.orm.xml`:\n\n```xml\n\u003C?xml version=\"1.0\" encoding=\"UTF-8\"?>\n\n\u003Cdoctrine-mapping xmlns=\"http:\u002F\u002Fdoctrine-project.org\u002Fschemas\u002Form\u002Fdoctrine-mapping\"\n                  xmlns:xsi=\"http:\u002F\u002Fwww.w3.org\u002F2001\u002FXMLSchema-instance\"\n                  xsi:schemaLocation=\"http:\u002F\u002Fdoctrine-project.org\u002Fschemas\u002Form\u002Fdoctrine-mapping\n                                      http:\u002F\u002Fdoctrine-project.org\u002Fschemas\u002Form\u002Fdoctrine-mapping.xsd\">\n\n    \u003Cmapped-superclass name=\"App\\Entity\\Product\\Product\" table=\"sylius_product\">\n\n        \u003Cfield name=\"samplesActive\" column=\"samples_active\" type=\"boolean\" \u002F>\n\n    \u003C\u002Fmapped-superclass>\n\n\u003C\u002Fdoctrine-mapping>\n```\n\n`config\u002Fdoctrine\u002FProductVariant.orm.xml`:\n\n```xml\n\u003C?xml version=\"1.0\" encoding=\"UTF-8\"?>\n\n\u003Cdoctrine-mapping xmlns=\"http:\u002F\u002Fdoctrine-project.org\u002Fschemas\u002Form\u002Fdoctrine-mapping\"\n                  xmlns:xsi=\"http:\u002F\u002Fwww.w3.org\u002F2001\u002FXMLSchema-instance\"\n                  xsi:schemaLocation=\"http:\u002F\u002Fdoctrine-project.org\u002Fschemas\u002Form\u002Fdoctrine-mapping\n                                      http:\u002F\u002Fdoctrine-project.org\u002Fschemas\u002Form\u002Fdoctrine-mapping.xsd\">\n\n    \u003Cmapped-superclass name=\"App\\Entity\\Product\\ProductVariant\" table=\"sylius_product_variant\">\n\n        \u003Cone-to-one field=\"sample\" target-entity=\"Sylius\\Component\\Product\\Model\\ProductVariantInterface\" mapped-by=\"sampleOf\">\n            \u003Ccascade>\n                \u003Ccascade-all \u002F>\n            \u003C\u002Fcascade>\n        \u003C\u002Fone-to-one>\n\n        \u003Cone-to-one field=\"sampleOf\" target-entity=\"Sylius\\Component\\Product\\Model\\ProductVariantInterface\" inversed-by=\"sample\">\n            \u003Ccascade>\n                \u003Ccascade-persist \u002F>\n            \u003C\u002Fcascade>\n            \u003Cjoin-column name=\"sample_of_id\" on-delete=\"SET NULL\" \u002F>\n        \u003C\u002Fone-to-one>\n\n    \u003C\u002Fmapped-superclass>\n\n\u003C\u002Fdoctrine-mapping>\n```\n\nOnce the mappings are in place, update your schema:\n\n```bash\nbin\u002Fconsole doctrine:migrations:diff\nbin\u002Fconsole doctrine:migrations:migrate\n```\n\n## Wire Up the Storefront\n\nEverything above is enough for the admin. The storefront needs the blocks and template overrides below to make samples available to customers.\n\n### Template Events\n\nAdd to `config\u002Fpackages\u002F_sylius.yaml`:\n\n```yaml\nsylius_ui:\n    events:\n        sylius.shop.cart.widget.popup:\n            blocks:\n                content:\n                    enabled: false\n                sample_aware_content:\n                    template: \"@BabDevSyliusProductSamplesPlugin\u002FShop\u002FCart\u002FWidget\u002F_popup.html.twig\"\n                    priority: 10\n\n        sylius.shop.checkout.sidebar:\n            blocks:\n                summary:\n                    enabled: false\n                sample_aware_summary:\n                    template: \"@BabDevSyliusProductSamplesPlugin\u002FShop\u002FCheckout\u002F_summary.html.twig\"\n                    priority: 20\n\n        sylius.shop.layout.javascripts:\n            blocks:\n                request_a_sample_javascript:\n                    template: 'JavaScript\u002Fplugin.html.twig'\n                    priority: 0\n```\n\nThe two `enabled: false` entries disable Sylius' own blocks; the plugin's replacements label sample line items as samples rather than repeating the product name.\n\n### Template Overrides\n\nSeveral core templates expose neither a Twig block nor a `sylius_template_event` at the point the plugin needs to change, so the plugin carries forks of them. Each fork opens with a header naming its upstream path, the Sylius version it was taken from, and its one intended difference — diff them against upstream when you upgrade Sylius.\n\nOverride each one from your application with a one-line include:\n\n```twig\n{# templates\u002Fbundles\u002FSyliusShopBundle\u002FProduct\u002FShow\u002F_addToCart.html.twig #}\n{% include '@BabDevSyliusProductSamplesPlugin\u002FShop\u002FProduct\u002FShow\u002F_addToCart.html.twig' %}\n```\n\n```twig\n{# templates\u002Fbundles\u002FSyliusShopBundle\u002FProduct\u002FShow\u002F_variants.html.twig #}\n{% include '@BabDevSyliusProductSamplesPlugin\u002FShop\u002FProduct\u002FShow\u002F_variants.html.twig' %}\n```\n\n```twig\n{# templates\u002Fbundles\u002FSyliusShopBundle\u002FProduct\u002FShow\u002F_variantsPricing.html.twig #}\n{% include '@BabDevSyliusProductSamplesPlugin\u002FShop\u002FProduct\u002FShow\u002F_variantsPricing.html.twig' with {'pricing': pricing, 'variants': variants} %}\n```\n\n```twig\n{# templates\u002Fbundles\u002FSyliusShopBundle\u002FProduct\u002F_info.html.twig #}\n{% include '@BabDevSyliusProductSamplesPlugin\u002FShop\u002FProduct\u002F_info.html.twig' %}\n```\n\n```twig\n{# templates\u002Fbundles\u002FSyliusAdminBundle\u002FProduct\u002F_info.html.twig #}\n{% include '@BabDevSyliusProductSamplesPlugin\u002FAdmin\u002FProduct\u002F_info.html.twig' %}\n```\n\nWhat each one contributes:\n\n| Override                             | Effect                                                                        |\n|--------------------------------------|-------------------------------------------------------------------------------|\n| `Shop\u002FProduct\u002FShow\u002F_addToCart`       | Adds the \"request a sample\" button next to \"add to cart\"                      |\n| `Shop\u002FProduct\u002FShow\u002F_variants`        | Emits the sample price data attributes the shop script reads                  |\n| `Shop\u002FProduct\u002FShow\u002F_variantsPricing` | Formats the sample price in the variant pricing map for products with options |\n| `Shop\u002FProduct\u002F_info`                 | Adds a sample badge to line items in the cart and order summaries             |\n| `Admin\u002FProduct\u002F_info`                | Adds a sample badge to line items in the admin order view                     |\n\nIf you have already forked any of these templates for your own reasons, merge the plugin's customizations into your template rather than replacing it.\n\n### Shop JavaScript\n\nThe plugin ships a JavaScript component that swaps the sample button's label and price as the shopper selects a variant. Publish the bundle assets:\n\n```bash\nbin\u002Fconsole assets:install public\n```\n\nThen add the template referenced by the `sylius.shop.layout.javascripts` block above:\n\n```twig\n{# templates\u002FJavaScript\u002Fplugin.html.twig #}\n{% if app.request.attributes.get('_route') == 'sylius_shop_product_show' %}\n    {% include '@SyliusUi\u002F_javascripts.html.twig' with {'path': 'bundles\u002Fbabdevsyliusproductsamplesplugin\u002Fbabdev-product-samples-shop.js'} %}\n{% endif %}\n```\n\nThe route guard keeps the script off every other page; it is only useful on the product page. If you build your storefront assets with Webpack Encore, you can instead import the plugin's source from `src\u002FResources\u002Fassets\u002Fshop\u002F` into your own entry point.\n",{"name":6,"slug":7,"description":8,"github":9,"packagistName":12,"packageType":13,"hasDocumentation":14,"supported":14,"visible":14,"versions":15},"Sylius Product Samples Plugin","product-samples-plugin","Adds support for product samples to Sylius applications.",{"owner":10,"repo":11},"BabDev","SyliusProductSamplesPlugin","babdev\u002Fsylius-product-samples-plugin","sylius-plugin",true,[16],{"version":17,"gitBranch":18,"released":19},"1.x","0.1",false,{"version":17,"gitBranch":18,"released":19},{"content":22,"package":23,"version":27},"- [Introduction](\u002Fopen-source\u002Fpackages\u002Fproduct-samples-plugin\u002Fdocs\u002F1.x\u002Fintro)\n- [Installation & Setup](\u002Fopen-source\u002Fpackages\u002Fproduct-samples-plugin\u002Fdocs\u002F1.x\u002Finstallation)\n- [Configuration](\u002Fopen-source\u002Fpackages\u002Fproduct-samples-plugin\u002Fdocs\u002F1.x\u002Fconfiguration)\n- [Usage](\u002Fopen-source\u002Fpackages\u002Fproduct-samples-plugin\u002Fdocs\u002F1.x\u002Fusage)\n",{"name":6,"slug":7,"description":8,"github":24,"packagistName":12,"packageType":13,"hasDocumentation":14,"supported":14,"visible":14,"versions":25},{"owner":10,"repo":11},[26],{"version":17,"gitBranch":18,"released":19},{"version":17,"gitBranch":18,"released":19},1790007747418]