Getting Started

Minimal Setup

Installation:
```
composer require sylius/core
```
Ensure you have sylius/resource-bundle and sylius/doctrine-bundle installed as dependencies, as they are core to Sylius's functionality.

Configuration: Add the bundles to your config/bundles.php:

return [
    // ...
    Sylius\Bundle\CoreBundle\SyliusCoreBundle::class => ['all' => true],
    Sylius\Bundle\ResourceBundle\SyliusResourceBundle::class => ['all' => true],
    Sylius\Bundle\DoctrineBundle\SyliusDoctrineBundle::class => ['all' => true],
];

Database Setup: Run migrations to create the required tables:
```
php bin/console doctrine:migrations:migrate
```

First Use Case: Create a product programmatically:

use Sylius\Component\Core\Model\Product;

$product = new Product();
$product->setName('Test Product');
$product->setSlug('test-product');
$product->setEnabled(true);

$productManager = $this->container->get('sylius.manager.product_manager');
$productManager->save($product);

Where to Look First

Documentation: Start with docs.sylius.com for detailed guides, especially the Getting Started section.
Entity Structure: Explore Sylius\Component\Core\Model for core entities like Product, Order, Customer, etc.
Services: Check Sylius\Bundle\CoreBundle\Resources/config/services.xml for key services like product_manager, order_manager, and cart_manager.

Implementation Patterns

Common Workflows

1. Product Management

CRUD Operations: Use the product_manager service to create, update, or delete products.

$product = $productManager->find(1); // Find by ID
$product->setPrice('19.99');
$productManager->save($product);

Variants and Options: Attach variants to products using ProductVariant and ProductOption:

$variant = new ProductVariant();
$variant->setProduct($product);
$variant->setOnHand(10);
$variant->setEnabled(true);
$productVariantManager->save($variant);

2. Order Processing

Cart Management: Use the cart_resolver and cart_manager to handle carts:

$cart = $cartManager->create();
$cartItem = new CartItem();
$cartItem->setProduct($product);
$cartItem->setQuantity(2);
$cartItem->setUnitPrice($product->getPrice());
$cart->add($cartItem);
$cartManager->persist($cart);

Order Completion: Convert a cart to an order and process payments/shipping:

$order = $orderManager->createFromCart($cart);
$order->setState(OrderInterface::STATE_COMPLETED);
$orderManager->save($order);

3. Customer Management

Registration and Authentication: Use Symfony's security system alongside Sylius's Customer entity:

$customer = new Customer();
$customer->setEmail('user@example.com');
$customer->setPlainPassword('securepassword');
$customerManager->save($customer);

Address Management: Attach addresses to customers:

$address = new Address();
$address->setFirstName('John');
$address->setStreet('123 Main St');
$customer->addAddress($address);
$customerManager->save($customer);

4. API Integration

RESTful Endpoints: Leverage Sylius's API platform integration to expose resources like products, orders, and customers:

# config/packages/api_platform.yaml
api_platform:
    formats:
        jsonld:
            mime_types: ['application/ld+json']
    patch_formats:
        json: true

GraphQL: Use sylius/graphql bundle for GraphQL queries/mutations:

query {
  products {
    edges {
      node {
        name
        slug
        price
      }
    }
  }
}

5. Event-Driven Architecture

Subscribing to Events: Listen to Sylius events (e.g., sylius.order.completed) to trigger custom logic:

use Sylius\Component\Core\Event\OrderCompletedEvent;

$eventDispatcher->addListener(OrderCompletedEvent::NAME, function (OrderCompletedEvent $event) {
    // Send email, update inventory, etc.
});

Common Events:
- sylius.order.placed
- sylius.product.created
- sylius.customer.registered

Integration Tips

1. Customizing Entities

Extend Sylius entities using Doctrine inheritance:

use Sylius\Component\Core\Model\Product as BaseProduct;

class CustomProduct extends BaseProduct
{
    private $customField;

    // Add getters/setters for customField
}

sylius_core:
    resources:
        product:
            classes:
                model: App\Entity\CustomProduct

2. Overriding Templates

Override Twig templates in your theme bundle:

templates/
    SyliusUi/
        Store/
            Product/
                show.html.twig

3. Adding Custom Fields

Use Sylius's Attribute system to add custom fields to entities:

$attribute = new Attribute();
$attribute->setType('pim_core_attribute_type_string');
$attribute->setCode('custom_field');
$attribute->setName('Custom Field');
$attributeManager->save($attribute);

Assign attributes to products:

$productAttributeValue = new ProductAttributeValue();
$productAttributeValue->setAttribute($attribute);
$productAttributeValue->setValue('Custom Value');
$product->addAttributeValue($productAttributeValue);

4. Testing

Use Sylius's test utilities for functional/integration tests:

use Sylius\Bundle\CoreBundle\Tests\Functional\WebTestCase;

class MyTest extends WebTestCase
{
    public function testSomething()
    {
        $client = static::createClient();
        $client->request('GET', '/products');
        // Assertions...
    }
}

Gotchas and Tips

Pitfalls

1. Entity Lifecycle Management

Detached Entities: Always ensure entities are managed by the EntityManager before saving:

$productManager->save($product); // Correct
$em->persist($product); // May fail if not managed by Sylius's manager

Cascading: Sylius entities often have cascading relationships (e.g., Product → ProductVariant). Be mindful of unintended saves/deletes.

2. State Machines

Order States: Orders have a strict state machine (e.g., cart → checkout → completed). Transition states explicitly:
```
$order->setState(OrderInterface::STATE_CHECKOUT); // Not $order->setState('checkout');
```
Custom States: Extending state machines requires careful handling of transitions and guards.

3. API Platform Quirks

Serialization Groups: Use #[Groups] attributes to control API output:

use ApiPlatform\Core\Annotation\Groups;

class Product
{
    #[Groups(['product:read'])]
    private $name;
}

Pagination: Sylius uses knplabs/knp-paginator-bundle by default. Configure pagination in api_platform.yaml:
```
api_platform:
    pagination_enabled: true
```

4. Doctrine Events

Lifecycle Callbacks: Sylius entities often have Doctrine lifecycle callbacks (e.g., prePersist). Overriding these requires caution to avoid conflicts.

5. Translation Management

Fallback Translations: Sylius uses sylius/translation for translations. Ensure fallback locales are configured in config/packages/sylius_core.yaml:
```
sylius_core:
    locales: [en_US, fr_FR]
    fallback_locale: en_US
```

Debugging Tips

1. Logging

Enable Sylius logging in config/packages/dev/monolog.yaml:

monolog:
    handlers:
        sylius:
            type: stream
            path

Core Laravel Package