Getting Started

Minimal Setup

Installation:
- Clone the repository into your project’s src/Awaresoft directory and symlink it:
```
mkdir -p src/Awaresoft
git clone [repo-url] src/Awaresoft/SonataBlockBundle
```
- Remove any existing Composer-installed version (if present) and update autoloader:
```
rm -rf vendor/awaresoft/sonata-block-bundle
composer dump-autoload
```

Enable the Bundle: Add to config/bundles.php:

return [
    // ...
    Awaresoft\SonataBlockBundle\SonataBlockBundle::class => ['all' => true],
];

First Use Case: Create a basic block type (e.g., TextBlock) in src/Entity/Block/TextBlock.php:

namespace App\Entity\Block;

use Awaresoft\SonataBlockBundle\Model\BlockInterface;

class TextBlock implements BlockInterface {
    private $content;
    // Implement BlockInterface methods (getType(), setSettings(), etc.)
}

sonata_block:
    blocks:
        text:
            class: App\Entity\Block\TextBlock
            type: text

Clear Cache:
```
php bin/console cache:clear
```

Implementation Patterns

Core Workflows

Block Creation & Management:
- Extend Awaresoft\SonataBlockBundle\Model\BlockInterface for custom blocks.
- Use the BlockManager service to fetch/manage blocks:
```
$blockManager = $this->container->get('sonata.block.manager');
$blocks = $blockManager->getBlocksByContext('admin');
```

Dynamic Block Rendering:

Override the block rendering logic in a custom service:

# config/services.yaml
services:
    App\Service\CustomBlockRenderer:
        arguments:
            - '@sonata.block.renderer'

class CustomBlockRenderer extends AbstractRenderer {
    public function renderBlock(BlockInterface $block) {
        // Custom logic
        return $this->renderView('blocks/custom.html.twig', ['block' => $block]);
    }
}

Block Contexts:
- Define contexts in sonata_block.yaml:
```
sonata_block:
    contexts:
        admin: ~
        frontend: ~
```
- Assign blocks to contexts via the admin panel or programmatically:
```
$block->setContext(['admin', 'frontend']);
```

Block Settings:

Use setSettings()/getSettings() to store block-specific data:

$block->setSettings(['color' => 'red']);
$settings = $block->getSettings();

Admin Integration:
- Enable the Sonata Admin bundle for block management:
```
sonata_admin:
    templates:
        layout: 'SonataAdminBundle::standard_layout.html.twig'
```
- Access the block admin at /admin/block.

Integration Tips

Twig Integration:
- Embed blocks in templates using:
```
{{ render(block) }}
```
- Pass context-specific blocks:
```
{{ render(blocks|render('frontend')) }}
```

Event Listeners:

Listen to block events (e.g., sonata.block.pre_render):

services:
    App\EventListener\BlockListener:
        tags:
            - { name: 'kernel.event_listener', event: 'sonata.block.pre_render', method: 'onPreRender' }

Database Schema:
- Extend the default block table schema in a migration:
```
$table->json('settings')->nullable(); // For custom settings
```

Security:

Secure block access via voters:

use Awaresoft\SonataBlockBundle\Security\BlockVoter;

security:
    access_control:
        - { path: ^/admin/block, roles: ROLE_ADMIN }

Gotchas and Tips

Pitfalls

Symlink Issues:
- Forgetting to symlink src/Awaresoft/SonataBlockBundle to the project root or not updating autoload_psr4.php will cause autoloading failures.
- Fix: Verify symlinks and run composer dump-autoload.
Backward Compatibility:
- Modifying the bundle directly may break dependent projects. Always test changes in isolation.
- Tip: Use feature branches and test with composer update awaresoft/sonata-block-bundle@dev.
Cache Invalidation:
- Changes to block configurations or templates may not reflect until cache is cleared:
```
php bin/console cache:pool:clear sonata_block.cache_pool
```
Context Mismatches:
- Blocks not appearing? Verify contexts are correctly defined in sonata_block.yaml and assigned to blocks.
Database Migrations:
- Custom block settings may require schema updates. Always back up before migrating.

Debugging

Block Not Rendering:
- Check if the block is enabled in sonata_block.yaml and assigned to a context.
- Verify the block class implements BlockInterface fully.
Settings Not Persisting:
- Ensure setSettings() is called before saving the block entity.
- Check if the database column for settings exists (e.g., json type in PostgreSQL).
Admin Panel Issues:
- Clear the Sonata cache:
```
php bin/console sonata:cache:clear
```
- Check for JavaScript errors in the browser console (Sonata Admin relies on JS).

Extension Points

Custom Block Types:
- Extend Awaresoft\SonataBlockBundle\Block\BaseBlockService for reusable block logic.
Block Renderers:
- Override Awaresoft\SonataBlockBundle\Renderer\RendererInterface for custom rendering pipelines.

Block Events:

Dispatch custom events (e.g., sonata.block.post_save) for post-processing:

$event = new BlockEvent($block);
$this->eventDispatcher->dispatch($event, 'sonata.block.post_save');

Block Settings Forms:
- Extend Awaresoft\SonataBlockBundle\Form\Type\BlockSettingsType for custom admin forms.
Block Security:
- Implement Awaresoft\SonataBlockBundle\Security\BlockInterface for granular permissions.

Pro Tips

Use sonata.block.manager to dynamically fetch blocks by context or type:
```
$blocks = $blockManager->getBlocksByType('text', 'frontend');
```

Leverage Twig Globals to expose blocks in all templates:

twig:
    globals:
        current_blocks: '@sonata.block.manager'

Batch Operations: Use the BlockManager to update multiple blocks:

$blockManager->updateBlocks($blocks, ['context' => ['frontend']]);

Testing: Mock BlockInterface in PHPUnit:

$block = $this->createMock(BlockInterface::class);
$block->method('getType')->willReturn('text');

Sonata Block Bundle Laravel Package