Kww Domstorlib C Laravel Package

Getting Started

Minimal Setup

1. Installation Add the package via Composer:

   composer require stepanets/kww-domstorlib-c
   

   Ensure your Laravel project targets PHP 5.6+ (last release compatibility).

2. First Use Case Basic initialization (adjust for your use case):

   use Kww\DomStorLib\DomStorLib;
   
   $domStorLib = new DomStorLib();
   $domStorLib->setBaseUrl('https://example.com');
   $domStorLib->setUserAgent('MyLaravelApp/1.0');
   

3. Where to Look

   • Source: GitHub (if available) (Note: Repository link is unknown; check for forks or alternative sources)
   • Documentation: Minimal. Focus on:
     • DomStorLib class methods (e.g., setBaseUrl, getPage, parseResponse).
     • Legacy PHP-C API wrappers (if applicable).

Implementation Patterns

Core Workflows

1. HTTP Requests Use for scraping or interacting with legacy systems:

   $response = $domStorLib->getPage('/api/data');
   $data = $domStorLib->parseResponse($response);
   

2. Data Parsing Chain parsing methods (if supported):

   $domStorLib->parseHtml($response)
              ->extractNodes('//div[@class="target"]')
              ->getText();
   

3. Integration with Laravel

   • Service Provider: Bind the library to the container for dependency injection:

     $this->app->singleton(DomStorLib::class, function ($app) {
         $lib = new DomStorLib();
         $lib->setBaseUrl(config('services.legacy_api.url'));
         return $lib;
     });
     

   • Facade (optional): Create a facade for cleaner syntax:

     // app/Facades/LegacyApi.php
     public static function getData() {
         return app(DomStorLib::class)->getPage('/data');
     }
     

4. Caching Responses Cache responses to avoid repeated requests:

   $cacheKey = 'legacy_data_' . md5('/api/data');
   $data = Cache::remember($cacheKey, now()->addHours(1), function () use ($domStorLib) {
       return $domStorLib->getPage('/api/data');
   });
   

Gotchas and Tips

Pitfalls

1. Deprecated Dependencies

   • The package relies on PHP-C extensions (e.g., dom, curl, or custom C bindings).
   • Fix: Ensure your server has these extensions enabled. Test with:

     php -m | grep -E 'dom|curl'
     

2. No Laravel-Specific Features

   • No built-in support for:
     • Queue jobs (e.g., dispatch()).
     • Eloquent models or database integration.
   • Workaround: Wrap calls in Laravel jobs or services.

3. Error Handling

   • The library lacks Laravel’s exception handling (e.g., throw_if).
   • Tip: Add custom validation:

     try {
         $response = $domStorLib->getPage('/data');
     } catch (\Exception $e) {
         Log::error("Legacy API failed: " . $e->getMessage());
         throw new \RuntimeException("API unavailable", 503);
     }
     

4. Legacy PHP-C API Quirks

   • Methods may return raw strings or objects. Inspect return types:

     // Example: Check if response is a DOMDocument
     if ($response instanceof DOMDocument) {
         // Parse with DOM methods
     }
     

Debugging Tips

1. Enable Verbose Logging Override methods to log requests/responses:

   $domStorLib->getPage = function ($url) {
       Log::debug("Requesting: " . $url);
       return parent::getPage($url);
   };
   

2. Test with curl First Verify endpoints manually before integrating:

   curl -v -A "MyLaravelApp/1.0" https://example.com/api/data
   

3. Fallback for Missing Extensions Use Laravel’s HTTP client as a backup:

   $client = new \GuzzleHttp\Client();
   $response = $client->get('https://example.com/api/data');
   

Extension Points

1. Custom Parsers Extend the library by adding methods:

   class ExtendedDomStorLib extends DomStorLib {
       public function extractJsonLd() {
           $response = $this->getPage('/data');
           return json_decode($response, true);
       }
   }
   

2. Event Listeners Dispatch events for critical actions (e.g., API failures):

   event(new LegacyApiRequested($url, $response));
   

3. Configuration Centralize settings in config/services.php:

   'legacy_api' => [
       'base_url' => env('LEGACY_API_URL'),
       'timeout' => 30,
   ],
   

   Then inject into the library:

   $domStorLib->setBaseUrl(config('services.legacy_api.base_url'));