Fiesta Online Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require aerisnet/fiesta-online-bundle
   

2. Configure Doctrine Update config/packages/doctrine.yaml with the provided dbal and orm configurations for the character connection (adjust CHARACTER_URL in .env). Example:

   dbal:
       connections:
           character:
               url: '%env(resolve:CHARACTER_URL)%'
               driver: 'pdo_sqlsrv'
               charset: UTF-8
   

3. First Use Case Inject AccountManager into a controller/service to fetch account data:

   use Aeris\FiestaOnlineBundle\Manager\AccountManager;
   
   public function showAccount(AccountManager $accountManager, int $accountId)
   {
       $account = $accountManager->getAccountById($accountId);
       return response()->json($account);
   }
   

Key Entry Points

• Entities: Located in vendor/aeris/fiesta-online-bundle/src/Entity/.
• Managers: AccountManager, CharacterManager (check src/Manager/ for others).
• Doctrine Configuration: Ensure character entity manager is properly mapped.

Implementation Patterns

Core Workflows

1. Account Management

   • Fetch accounts by ID: $accountManager->getAccountById($id).
   • List all accounts: $accountManager->getAllAccounts().
   • Tip: Cache results if frequent reads are expected (e.g., Illuminate\Support\Facades\Cache).

2. Character Data

   • Use CharacterManager to interact with character data:

     $character = $characterManager->getCharacterById($id);
     $characters = $characterManager->getCharactersByAccount($accountId);
     

3. Database Connection Handling

   • The bundle uses a separate Doctrine connection (character). Always prefix queries with the character entity manager:

     $em = $this->getDoctrine()->getManager('character');
     $character = $em->getRepository('Character')->find($id);
     

Integration Tips

• Laravel-Specific Adaptations Replace Symfony’s dependency injection with Laravel’s service container:

  $accountManager = app('Aeris\FiestaOnlineBundle\Manager\AccountManager');
  

• API Layer Wrap managers in a DTO/Resource layer for consistency:

  return new AccountResource($accountManager->getAccountById($id));
  

• Event Listeners Extend functionality by listening to Doctrine events (e.g., post-load for character data transformation).

Gotchas and Tips

Pitfalls

1. Connection Configuration

   • Issue: pdo_sqlsrv may not be installed by default.
   • Fix: Install the driver (pecl install pdo_sqlsrv) and ensure .env has the correct CHARACTER_URL (e.g., sqlsrv://user:pass@host:port/database).
   • Debug: Check doctrine:schema:validate for connection errors.

2. Entity Manager Scope

   • Issue: Forgetting to specify the character entity manager when querying.
   • Fix: Always use $this->getDoctrine()->getManager('character') or inject the manager explicitly.

3. Outdated Dependencies

   • Issue: The package hasn’t been updated since 2021. Some Symfony/Laravel features (e.g., PHP 8.1+) may not work out-of-the-box.
   • Fix: Override or extend classes in app/Extensions/ to patch incompatibilities.

Debugging Tips

• Query Logging Enable SQL logging in config/packages/dev/doctrine.yaml:

  doctrine:
      dbal:
          logging: true
          profiling: true
  

• Entity Mapping Verify mappings with:

  php bin/console doctrine:mapping:info --em=character
  

Extension Points

1. Custom Managers Extend existing managers (e.g., AccountManager) to add business logic:

   class CustomAccountManager extends AccountManager {
       public function getActiveAccounts() {
           return $this->createQueryBuilder('u')
               ->where('u.isActive = :active')
               ->setParameter('active', true)
               ->getQuery()
               ->getResult();
       }
   }
   

2. New Entities Add custom entities by extending the bundle’s structure:

   • Place in app/Entity/FiestaOnline/ (or similar).
   • Register in config/packages/doctrine.yaml under the character entity manager.

3. Event Subscribers Listen for Doctrine lifecycle events (e.g., postLoad) to transform data:

   use Doctrine\Common\EventSubscriber;
   
   class CharacterSubscriber implements EventSubscriber {
       public function getSubscribedEvents() {
           return ['postLoad'];
       }
   
       public function postLoad(LifecycleEventArgs $args) {
           $entity = $args->getObject();
           if ($entity instanceof \Aeris\FiestaOnlineBundle\Entity\Character) {
               // Transform data here
           }
       }
   }