Glyph Lists Laravel Package

Getting Started

Minimal Steps

1. Installation

   composer require prinsfrank/glyph-lists
   

   Ensure your project uses PHP 8.1+ (enums are required).

2. First Use Case: Validate a Glyph Check if a glyph exists in the Adobe Glyph List:

   use PrinsFrank\GlyphLists\AdobeGlyphList;
   
   if (AdobeGlyphList::A->value === 'A') {
       // Glyph 'A' is valid
   }
   

   Or dynamically:

   $isValid = AdobeGlyphList::tryFrom('A') !== null;
   

3. Where to Look First

   • Enum Classes: Browse vendor/prinsfrank/glyph-lists/src/Enums/ for available lists (e.g., AdobeGlyphList.php, AdobeGlyphListForNewNames.php).
   • Facade (Optional): Use PrinsFrank\GlyphLists\Facades\GlyphLists for container-bound access:

     $glyph = GlyphLists::get('AdobeGlyphList')->A;
     

   • Adobe Source: Refer to the original AGL/AGLF data for glyph meanings.

Implementation Patterns

Usage Patterns

1. Type-Safe Glyph Handling Replace raw strings with enums in validation, APIs, or business logic:

   // Before (string-based)
   if ($glyph === 'A') { ... }
   
   // After (enum-based)
   if ($glyphEnum === AdobeGlyphList::A) { ... }
   

2. Laravel Integration

   • Service Provider: Bind the facade in AppServiceProvider:

     public function register() {
         $this->app->bind('glyphLists', function () {
             return new \PrinsFrank\GlyphLists\GlyphLists();
         });
     }
     

   • Validation Rules: Create a custom rule:

     use PrinsFrank\GlyphLists\AdobeGlyphList;
     use Illuminate\Validation\Rule;
     
     $validator->extend('valid_adobe_glyph', function ($attribute, $value, $parameters) {
         return AdobeGlyphList::tryFrom($value) !== null;
     });
     

     Usage:

     'glyph' => ['required', 'valid_adobe_glyph'],
     

3. PDF/Font Libraries Use enums to ensure glyph compatibility in libraries like barryvdh/laravel-dompdf:

   $dompdf = new \Dompdf\Dompdf();
   $dompdf->loadHtml($html);
   
   // Validate glyphs before rendering
   $glyphsInHtml = extractGlyphsFromHtml($html);
   foreach ($glyphsInHtml as $glyph) {
       if (AdobeGlyphList::tryFrom($glyph) === null) {
           throw new \InvalidArgumentException("Unsupported glyph: $glyph");
       }
   }
   

4. Dynamic Glyph Lookup Convert between Unicode code points and glyph names:

   // Unicode to Glyph
   $glyph = AdobeGlyphList::fromCode(0x41); // Returns AdobeGlyphList::A
   
   // Glyph to Unicode
   $code = AdobeGlyphList::A->code; // Returns 65 (Unicode for 'A')
   

5. Batch Operations Iterate over all glyphs for bulk processing (e.g., font generation):

   foreach (AdobeGlyphList::cases() as $glyph) {
       $this->fontRenderer->addGlyph($glyph->value, $glyph->code);
   }
   

Workflows

1. Font Validation Pipeline

   • Step 1: Extract glyphs from user input (e.g., text fields, PDFs).
   • Step 2: Validate against AdobeGlyphList:

     $validGlyphs = array_filter($extractedGlyphs, fn($glyph) =>
         AdobeGlyphList::tryFrom($glyph) !== null
     );
     

   • Step 3: Proceed with processing or reject invalid glyphs.

2. Unicode Normalization Ensure text uses only supported glyphs:

   $normalizedText = str_replace(
       array_map(fn($glyph) => $glyph->value, AdobeGlyphList::cases()),
       array_map(fn($glyph) => $glyph->value, AdobeGlyphList::cases()),
       $inputText
   );
   

3. Localization Tools Map glyphs to locale-specific representations:

   $localeGlyphs = match ($locale) {
       'ar' => AdobeGlyphListForNewNames::cases(),
       default => AdobeGlyphList::cases(),
   };
   

Integration Tips

• Autoloading: The package follows PSR-4, so no additional config is needed.
• Caching: Enums are loaded once; no need for manual caching unless processing millions of glyphs.
• Testing: Mock enums in unit tests:

  $mockGlyph = $this->createMock(AdobeGlyphList::class);
  $mockGlyph->method('value')->willReturn('A');
  

• IDE Support: Use enums for autocompletion (e.g., AdobeGlyphList:: shows all available glyphs).

Gotchas and Tips

Pitfalls

1. PHP Version Requirement

   • Gotcha: Enums require PHP 8.1+. Using this package on older versions will fail with:

     Fatal error: Class 'PrinsFrank\GlyphLists\AdobeGlyphList' not found
     

   • Fix: Upgrade PHP or avoid this package.

2. Static Data Limitations

   • Gotcha: The package provides static, pre-parsed data. Adding new glyphs requires:
     • Forking the package.
     • Extending enums manually (not designed for runtime additions).
   • Workaround: Create a wrapper class to merge custom glyphs:

     class ExtendedGlyphList {
         public static function all(): array {
             return array_merge(
                 AdobeGlyphList::cases(),
                 [new CustomGlyphList('Z'), ...]
             );
         }
     }
     

3. Case Sensitivity

   • Gotcha: Glyph names are case-sensitive (e.g., AdobeGlyphList::A ≠ AdobeGlyphList::a).
   • Tip: Normalize input before validation:

     $normalizedGlyph = strtoupper($userInput);
     

4. Missing Glyphs

   • Gotcha: Not all Unicode glyphs are included (only those in Adobe’s AGL/AGLF).
   • Tip: Cross-reference with Unicode Consortium data for completeness.

5. Facade Ambiguity

   • Gotcha: The facade (GlyphLists) may not be auto-discovered if not registered.
   • Fix: Manually bind it in AppServiceProvider:

     $this->app->singleton('glyphLists', function () {
         return new \PrinsFrank\GlyphLists\Facades\GlyphLists();
     });
     

Debugging

1. Enum Not Found Errors

   • Cause: Typos in glyph names (e.g., AdobeGlyphList::a instead of AdobeGlyphList::A).
   • Debug: Use AdobeGlyphList::cases() to list all valid glyphs:

     print_r(array_column(AdobeGlyphList::cases(), 'value'));
     

2. Performance Bottlenecks

   • Cause: Repeatedly calling AdobeGlyphList::tryFrom() in loops.
   • Fix: Cache results:

     $cache = [];
     $isValid = $cache[$glyph] ??= AdobeGlyphList::tryFrom($glyph) !== null;
     

3. Integration Issues

   • Cause: Conflicts with other packages using the same namespace.
   • Fix: Use fully qualified names:

     use PrinsFrank\GlyphLists\AdobeGlyphList as AdobeGlyphListEnum;
     

Configuration Quirks

1. No Laravel-Specific Config
   • Quirk: The package has no config/glyph-lists.php file.
   • Tip: Extend it if needed:

     // config/glyph-lists.php
     return [
         'default_list' => 'AdobeGlyphList',
         'custom_glyphs' => ['Z'