Ting Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require ccmbenchmark/ting_bundle
   

   Register the bundle in config/bundles.php (Laravel 4.x+):

   return [
       // ...
       CCMBenchmark\TingBundle\TingBundle::class => ['all' => true],
   ];
   

2. First Use Case: Annotate an entity with metadata (e.g., src/Entity/User.php):

   use CCMBenchmark\TingBundle\Annotation\Ting;
   
   /**
    * @Ting\Table(name="users")
    */
   class User {}
   

   Run php bin/console cache:clear to process annotations.

Where to Look First

• Configuration: config/packages/ting.yaml (auto-generated after installation).
• Annotations: Check CCMBenchmark\TingBundle\Annotation for available attributes.
• Doctrine Integration: Verify TingBundle is loaded in config/bundles.php.

Implementation Patterns

1. Entity Metadata with Attributes

Replace YAML/XML metadata with PHP attributes (recommended for new projects):

use CCMBenchmark\TingBundle\Annotation\Ting;

class Product {
    /**
     * @Ting\Column(type="string", length=255)
     * @Ting\Unique(name="product_code_unique")
     */
    private $code;
}

Workflow:

1. Annotate entities.
2. Clear cache (cache:clear).
3. Use TingBundle services (e.g., ting.repository_manager).

2. Custom Repository Configuration

Override default repository behavior via config/packages/ting.yaml:

ting:
    repositories:
        App:
            namespace: App\Entity
            directory: "%kernel.project_dir%/src/Entity"
            options:
                App\Entity\UserRepository:
                    connection: custom_db
                    extra:
                        cache_driver: redis

Integration Tip: Use ting.repository_manager.get_repository() to fetch repositories with custom options.

3. User Provider Integration

Extend Symfony’s security system:

# config/packages/security.yaml
security:
    providers:
        ting_provider:
            id: ting.security.user.provider

Workflow:

1. Implement UserInterface in your entity.
2. Configure the provider.
3. Use ting.security.user.provider in your firewall.

4. Value Resolver for APIs

Resolve dynamic values in API platforms:

use CCMBenchmark\TingBundle\Resolver\TingValueResolver;

class ProductController {
    public function __construct(
        private TingValueResolver $tingResolver
    ) {}

    public function show(Product $product) {
        $resolved = $this->tingResolver->resolve($product);
        return $resolved;
    }
}

Tip: Register the resolver in api_platform.metadata.factory if using API Platform.

Gotchas and Tips

Pitfalls

1. Cache Dependency:

   • Annotations require cache:clear after changes. Use cache:warmup in CI/CD.
   • Debugging: Check var/cache/dev/annotations for processed metadata.

2. Doctrine DBAL vs. ORM:

   • TingBundle primarily uses DBAL. For ORM features (e.g., @ORM\Entity), ensure doctrine/orm is installed.
   • Fix: Add doctrine/doctrine-bundle if missing.

3. Connection Mismatches:

   • If connection: main fails, verify database_url in .env or config/packages/doctrine.yaml.
   • Tip: Use ting.connections to define multiple DBs:

     ting:
         connections:
             main: { url: "mysql://user:pass@localhost/db" }
             replica: { url: "mysql://user:pass@replica/db" }
     

Debugging

1. Metadata Dumping:

   php bin/console debug:ting
   

   Lists all registered tables, columns, and constraints.

2. Annotation Errors:

   • Enable dev mode and check logs for Ting\Exception\MetadataException.
   • Quick Fix: Validate annotations with:

     php bin/console cache:clear --env=dev --no-debug
     

Extension Points

1. Custom Annotations: Extend CCMBenchmark\TingBundle\Annotation\Ting:

   namespace App\Annotation;
   use Doctrine\Common\Annotations\Annotation;
   
   /**
    * @Annotation
    * @Target({"CLASS", "PROPERTY"})
    */
   class CustomTing extends Annotation {}
   

   Register in services.yaml:

   ting.annotation_reader:
       tags: [ting.annotation_reader]
   

2. Event Listeners: Subscribe to Ting events (e.g., TingEvents::POST_METADATA_BUILD):

   use CCMBenchmark\TingBundle\Event\MetadataEvent;
   use Symfony\Component\EventDispatcher\EventSubscriberInterface;
   
   class TingSubscriber implements EventSubscriberInterface {
       public static function getSubscribedEvents() {
           return [
               TingEvents::POST_METADATA_BUILD => 'onMetadataBuild',
           ];
       }
   
       public function onMetadataBuild(MetadataEvent $event) {
           $event->addTable('custom_table');
       }
   }
   

Configuration Quirks

1. Namespace Conflicts:

   • If namespace in ting.repositories is incorrect, Ting skips the directory.
   • Validation: Use absolute paths (e.g., directory: "%kernel.project_dir%/src/Entity").

2. Default Options:

   • default under options applies to all repositories unless overridden.
   • Example:

     ting:
         repositories:
             App:
                 options:
                     default:
                         connection: main
                         cache: true
                     App\Entity\AdminRepository:
                         cache: false
     

3. Public Properties:

   • TingBundle ignores public properties by default (unlike Doctrine ORM).
   • Workaround: Use @Ting\Column on public properties or make them private.