Cssxpath Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require phpgt/cssxpath
   

   No additional configuration is required—just autoload.

2. First Use Case Convert a simple CSS selector to XPath:

   use Phpgt\CssXpath\CssXpath;
   
   $cssXpath = new CssXpath();
   $xpath = $cssXpath->cssToXpath('div.content > p');
   echo $xpath; // Output: "//div[contains(@class, 'content')]/p"
   

3. Where to Look First

   • Source Code (if available) for edge cases.
   • Test suite (tests/ folder) for usage examples.
   • Focus on CssXpath::cssToXpath()—the core method.

Implementation Patterns

Core Workflow

1. Selector Conversion

   $converter = new CssXpath();
   $xpath = $converter->cssToXpath('article.post:first-child h2');
   // Output: "//article[contains(@class, 'post')][1]/h2"
   

2. Integration with DOM Parsing

   use Phpgt\CssXpath\CssXpath;
   use DOMDocument;
   
   $dom = new DOMDocument();
   $dom->loadHTML('<div class="user"><span>John</span></div>');
   
   $converter = new CssXpath();
   $xpath = $converter->cssToXpath('div.user span');
   $elements = $dom->evaluate($xpath);
   

3. Batch Processing

   $selectors = ['.header', '#main', 'li.active'];
   $converter = new CssXpath();
   
   foreach ($selectors as $selector) {
       $xpath = $converter->cssToXpath($selector);
       // Use $xpath in queries
   }
   

Advanced Patterns

• Dynamic Selector Handling

  $userInput = request('selector');
  $xpath = (new CssXpath())->cssToXpath($userInput);
  // Sanitize $userInput first to avoid XSS!
  

• Combining with Laravel Collections

  $html = '<div class="items"><span>1</span><span>2</span></div>';
  $dom = new DOMDocument();
  $dom->loadHTML($html);
  
  collect(['span', '.items span'])
      ->map(fn($sel) => (new CssXpath())->cssToXpath($sel))
      ->each(fn($xpath) => $dom->evaluate($xpath));
  

Gotchas and Tips

Pitfalls

1. Attribute Selector Quirks

   • CSS div[href] becomes XPath //div[@href] (works), but div[href^="http"] may not map perfectly to XPath’s starts-with().
   • Fix: Manually adjust complex attribute selectors if needed.

2. Pseudo-classes

   • :nth-child(2n) converts to [position()=2 or position()=4 or ...]—verbose but correct.
   • Tip: Cache converted XPath for repeated use.

3. Namespaces

   • No built-in namespace support (e.g., html:div). Extend the class or prepend namespaces manually:

     $xpath = '//ns:div[contains(@class, "content")]';
     

4. Performance

   • Avoid converting all selectors at once for large datasets. Process selectively.

Debugging

• Validate Output

  $xpath = $converter->cssToXpath('div > p:first-of-type');
  $dom->evaluate($xpath); // Throws exception if invalid
  

• Log Conversions

  $converter = new CssXpath();
  $converter->setDebug(true); // Hypothetical; check if supported
  

Extension Points

1. Custom Rules Override Phpgt\CssXpath\CssXpath and extend cssToXpath():

   class CustomCssXpath extends CssXpath {
       protected function handlePseudoClass($pseudo) {
           // Custom logic for :custom-pseudo
       }
   }
   

2. Pre/Post-Processing

   $rawXpath = $converter->cssToXpath('div');
   $finalXpath = "//root/$rawXpath"; // Inject into larger query
   

3. Testing

   • Mock DOMDocument to test XPath results:

     $dom = $this->createMock(DOMDocument::class);
     $dom->method('evaluate')->willReturn(new DOMNodeList());