Name Parser Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require theiconic/name-parser
   

   No additional configuration is required—just autoload the package.

2. First Use Case Parse a name string into structured components:

   use TheIconic\NameParser\NameParser;
   
   $parser = new NameParser();
   $result = $parser->parse('John Michael Doe');
   
   // Outputs structured data:
   // [
   //   'first_name' => 'John',
   //   'middle_name' => 'Michael',
   //   'last_name' => 'Doe',
   //   'suffix' => null,
   //   'prefix' => null,
   //   'full_name' => 'John Michael Doe'
   // ]
   

3. Where to Look First

   • Class Docs: NameParser class methods (parse(), parseWithOptions()).
   • Default Rules: Inspect NameParser::DEFAULT_RULES for built-in heuristics (e.g., suffixes like "Jr.", prefixes like "Dr.").
   • Tests: Check the package’s test suite for edge cases (e.g., hyphenated names, non-Latin scripts).

Implementation Patterns

Core Workflows

1. Basic Parsing

   $parser = new NameParser();
   $nameData = $parser->parse('Vanessa Anne Smith-Johnson');
   

   • Handles hyphenated last names and multi-word first/middle names.

2. Custom Rules Override default rules for domain-specific needs:

   $customRules = [
       'prefixes' => ['Prof.', 'Rev.'],
       'suffixes' => ['PhD', 'MD'],
   ];
   $parser = new NameParser($customRules);
   $result = $parser->parse('Prof. Maria Garcia PhD');
   

3. Integration with Laravel

   • Form Request Validation:

     use Illuminate\Validation\Rule;
     
     $validator->after(function ($validator) {
         $name = $validator->getData()['name'];
         $parser = new NameParser();
         $parsed = $parser->parse($name);
         $validator->errors()->merge([
             'name' => [
                 Rule::required()->message('Name is required.'),
                 Rule::string()->message('Name must be a string.'),
             ],
         ]);
     });
     

   • Eloquent Model Casting:

     protected $casts = [
         'full_name' => NameParser::class,
     ];
     

4. Batch Processing Parse arrays of names efficiently:

   $names = ['Alice', 'Bob Jr.', 'Charlie van Dijk'];
   $parser = new NameParser();
   $results = array_map([$parser, 'parse'], $names);
   

Advanced Patterns

• Localization: Extend for non-Latin scripts by subclassing NameParser and overriding parse().
• Fallback Logic: Combine with other libraries (e.g., league/address for international names) for robustness.

Gotchas and Tips

Pitfalls

1. False Positives in Rules

   • Default rules may misclassify names (e.g., "Mac" as a prefix instead of part of a last name like "MacDonald").
   • Fix: Use parseWithOptions() to disable ambiguous rules:

     $parser->parseWithOptions('MacDonald', ['strict' => true]);
     

2. Performance with Large Datasets

   • Parsing thousands of names sequentially can be slow.
   • Fix: Use parallel processing (e.g., Laravel queues) or cache results.

3. Edge Cases

   • Names with apostrophes (O'Connor), non-standard formats (123 Main St), or empty strings.
   • Tip: Validate input before parsing:

     if (empty($name) || !is_string($name)) {
         throw new \InvalidArgumentException('Invalid name format.');
     }
     

Debugging Tips

• Inspect Rules: Dump the parser’s rules to debug misclassifications:

  var_dump($parser->getRules());
  

• Log Parsed Output: Compare expected vs. actual results:

  \Log::debug('Parsed name:', $parsedData);
  

Extension Points

1. Custom Parsers Extend NameParser for domain-specific logic:

   class MedicalNameParser extends NameParser {
       protected function getRules() {
           $rules = parent::getRules();
           $rules['suffixes'][] = 'DO'; // Medical suffix
           return $rules;
       }
   }
   

2. Plugin System Dynamically add rules at runtime:

   $parser = new NameParser();
   $parser->addRule('prefixes', ['Sir']);
   $parser->addRule('suffixes', ['Esq.']);
   

3. Integration with Laravel Services Bind the parser to the container for dependency injection:

   $this->app->singleton(NameParser::class, function ($app) {
       return new NameParser($app['config']['name_parser.rules']);
   });