# PHP CSS Parser
  
  [![Build Status](https://github.com/sabberworm/PHP-CSS-Parser/workflows/CI/badge.svg?branch=master)](https://github.com/sabberworm/PHP-CSS-Parser/actions/)
  
  A Parser for CSS Files written in PHP. Allows extraction of CSS files into a data structure, manipulation of said structure and output as (optimized) CSS.
  
  ## Usage
  
  ### Installation using Composer
  
  ```bash
  composer require sabberworm/php-css-parser
  ```
  
  ### Extraction
  
  To use the CSS Parser, create a new instance. The constructor takes the following form:
  
  ```php
  new \Sabberworm\CSS\Parser($css);
  ```
  
  To read a file, for example, you’d do the following:
  
  ```php
  $parser = new \Sabberworm\CSS\Parser(file_get_contents('somefile.css'));
  $cssDocument = $parser->parse();
  ```
  
  The resulting CSS document structure can be manipulated prior to being output.
  
  ### Options
  
  #### Charset
  
  The charset option will only be used if the CSS file does not contain an `@charset` declaration. UTF-8 is the default, so you won’t have to create a settings object at all if you don’t intend to change that.
  
  ```php
  $settings = \Sabberworm\CSS\Settings::create()
      ->withDefaultCharset('windows-1252');
  $parser = new \Sabberworm\CSS\Parser($css, $settings);
  ```
  
  #### Strict parsing
  
  To have the parser throw an exception when encountering invalid/unknown constructs (as opposed to trying to ignore them and carry on parsing), supply a thusly configured `\Sabberworm\CSS\Settings` object:
  
  ```php
  $parser = new \Sabberworm\CSS\Parser(
      file_get_contents('somefile.css'),
      \Sabberworm\CSS\Settings::create()->beStrict()
  );
  ```
  
  Note that this will also disable a workaround for parsing the unquoted variant of the legacy IE-specific `filter` rule.
  
  #### Disable multibyte functions
  
  To achieve faster parsing, you can choose to have PHP-CSS-Parser use regular string functions instead of `mb_*` functions. This should work fine in most cases, even for UTF-8 files, as all the multibyte characters are in string literals. Still it’s not recommended using this with input you have no control over as it’s not thoroughly covered by test cases.
  
  ```php
  $settings = \Sabberworm\CSS\Settings::create()->withMultibyteSupport(false);
  $parser = new \Sabberworm\CSS\Parser($css, $settings);
  ```
  
  ### Manipulation
  
  The resulting data structure consists mainly of five basic types: `CSSList`, `RuleSet`, `Rule`, `Selector` and `Value`. There are two additional types used: `Import` and `Charset`, which you won’t use often.
  
  #### CSSList
  
  `CSSList` represents a generic CSS container, most likely containing declaration blocks (rule sets with a selector), but it may also contain at-rules, charset declarations, etc.
  
  To access the items stored in a `CSSList` – like the document you got back when calling `$parser->parse()` –, use `getContents()`, then iterate over that collection and use `instanceof` to check whether you’re dealing with another `CSSList`, a `RuleSet`, a `Import` or a `Charset`.
  
  To append a new item (selector, media query, etc.) to an existing `CSSList`, construct it using the constructor for this class and use the `append($oItem)` method.
  
  #### RuleSet
  
  `RuleSet` is a container for individual rules. The most common form of a rule set is one constrained by a selector. The following concrete subtypes exist:
  
  * `AtRuleSet` – for generic at-rules for generic at-rules which are not covered by specific classes, i.e., not `@import`, `@charset` or `@media`. A common example for this is `@font-face`.
  * `DeclarationBlock` – a `RuleSet` constrained by a `Selector`; contains an array of selector objects (comma-separated in the CSS) as well as the rules to be applied to the matching elements.
  
  Note: A `CSSList` can contain other `CSSList`s (and `Import`s as well as a `Charset`), while a `RuleSet` can only contain `Rule`s.
  
  If you want to manipulate a `RuleSet`, use the methods `addRule(Rule $rule)`, `getRules()` and `removeRule($rule)` (which accepts either a `Rule` or a rule name; optionally suffixed by a dash to remove all related rules).
  
  #### Rule
  
  `Rule`s just have a string key (the rule) and a `Value`.
  
  #### Value
  
  `Value` is an abstract class that only defines the `render` method. The concrete subclasses for atomic value types are:
  
  * `Size` – consists of a numeric `size` value and a unit.
  * `Color` – colors can be input in the form #rrggbb, #rgb or schema(val1, val2, …) but are always stored as an array of ('s' => val1, 'c' => val2, 'h' => val3, …) and output in the second form.
  * `CSSString` – this is just a wrapper for quoted strings to distinguish them from keywords; always output with double quotes.
  * `URL` – URLs in CSS; always output in `URL("")` notation.
  
  There is another abstract subclass of `Value`, `ValueList`: A `ValueList` represents a lists of `Value`s, separated by some separation character (mostly `,`, whitespace, or `/`).
  
  There are two types of `ValueList`s:
  
  * `RuleValueList` – The default type, used to represent all multivalued rules like `font: bold 12px/3 Helvetica, Verdana, sans-serif;` (where the value would be a whitespace-separated list of the primitive value `bold`, a slash-separated list and a comma-separated list).
  * `CSSFunction` – A special kind of value that also contains a function name and where the values are the function’s arguments. Also handles equals-sign-separated argument lists like `filter: alpha(opacity=90);`.
  
  #### Convenience methods
  
  There are a few convenience methods on `Document` to ease finding, manipulating and deleting rules:
  
  * `getAllDeclarationBlocks()` – does what it says; no matter how deeply nested the selectors are. Aliased as `getAllSelectors()`.
  * `getAllRuleSets()` – does what it says; no matter how deeply nested the rule sets are.
  * `getAllValues()` – finds all `Value` objects inside `Rule`s.
  
  ## To-Do
  
  * More convenience methods (like `selectorsWithElement($sId/Class/TagName)`, `attributesOfType($type)`, `removeAttributesOfType($type)`)
  * Real multibyte support. Currently, only multibyte charsets whose first 255 code points take up only one byte and are identical with ASCII are supported (yes, UTF-8 fits this description).
  * Named color support (using `Color` instead of an anonymous string literal)
  
  ## Use cases
  
  ### Use `Parser` to prepend an ID to all selectors
  
  ```php
  $myId = "#my_id";
  $parser = new \Sabberworm\CSS\Parser($css);
  $cssDocument = $parser->parse();
  foreach ($cssDocument->getAllDeclarationBlocks() as $block) {
      foreach ($block->getSelectors() as $selector) {
          // Loop over all selector parts (the comma-separated strings in a
          // selector) and prepend the ID.
          $selector->setSelector($myId.' '.$selector->getSelector());
      }
  }
  ```
  
  ### Shrink all absolute sizes to half
  
  ```php
  $parser = new \Sabberworm\CSS\Parser($css);
  $cssDocument = $parser->parse();
  foreach ($cssDocument->getAllValues() as $value) {
      if ($value instanceof CSSSize && !$value->isRelative()) {
          $value->setSize($value->getSize() / 2);
      }
  }
  ```
  
  ### Remove unwanted rules
  
  ```php
  $parser = new \Sabberworm\CSS\Parser($css);
  $cssDocument = $parser->parse();
  foreach($cssDocument->getAllRuleSets() as $oRuleSet) {
      // Note that the added dash will make this remove all rules starting with
      // `font-` (like `font-size`, `font-weight`, etc.) as well as a potential
      // `font` rule.
      $oRuleSet->removeRule('font-'); 
      $oRuleSet->removeRule('cursor');
  }
  ```
  
  ### Output
  
  To output the entire CSS document into a variable, just use `->render()`:
  
  ```php
  $parser = new \Sabberworm\CSS\Parser(file_get_contents('somefile.css'));
  $cssDocument = $parser->parse();
  print $cssDocument->render();
  ```
  
  If you want to format the output, pass an instance of type `\Sabberworm\CSS\OutputFormat`:
  
  ```php
  $format = \Sabberworm\CSS\OutputFormat::create()
      ->indentWithSpaces(4)->setSpaceBetweenRules("
  ");
  print $cssDocument->render($format);
  ```
  
  Or use one of the predefined formats:
  
  ```php
  print $cssDocument->render(Sabberworm\CSS\OutputFormat::createPretty());
  print $cssDocument->render(Sabberworm\CSS\OutputFormat::createCompact());
  ```
  
  To see what you can do with output formatting, look at the tests in `tests/OutputFormatTest.php`.
  
  ## Examples
  
  ### Example 1 (At-Rules)
  
  #### Input
  
  ```css
  @charset "utf-8";
  
  @font-face {
    font-family: "CrassRoots";
    src: url("../media/cr.ttf");
  }
  
  html, body {
      font-size: 1.6em;
  }
  
  @keyframes mymove {
      from { top: 0px; }
      to { top: 200px; }
  }
  
  ```
  
  <details>
    <summary><b>Structure (<code>var_dump()</code>)</b></summary>
  
  ```php
  class Sabberworm\CSS\CSSList\Document#4 (2) {
    protected $aContents =>
    array(4) {
      [0] =>
      class Sabberworm\CSS\Property\Charset#6 (2) {
        private $sCharset =>
        class Sabberworm\CSS\Value\CSSString#5 (2) {
          private $sString =>
          string(5) "utf-8"
          protected $iLineNo =>
          int(1)
        }
        protected $iLineNo =>
        int(1)
      }
      [1] =>
      class Sabberworm\CSS\RuleSet\AtRuleSet#7 (4) {
        private $sType =>
        string(9) "font-face"
        private $sArgs =>
        string(0) ""
        private $aRules =>
        array(2) {
          'font-family' =>
          array(1) {
            [0] =>
            class Sabberworm\CSS\Rule\Rule#8 (4) {
              private $sRule =>
              string(11) "font-family"
              private $mValue =>
              class Sabberworm\CSS\Value\CSSString#9 (2) {
                private $sString =>
                string(10) "CrassRoots"
                protected $iLineNo =>
                int(4)
              }
              private $bIsImportant =>
              bool(false)
              protected $iLineNo =>
              int(4)
            }
          }
          'src' =>
          array(1) {
            [0] =>
            class Sabberworm\CSS\Rule\Rule#10 (4) {
              private $sRule =>
              string(3) "src"
              private $mValue =>
              class Sabberworm\CSS\Value\URL#11 (2) {
                private $oURL =>
                class Sabberworm\CSS\Value\CSSString#12 (2) {
                  private $sString =>
                  string(15) "../media/cr.ttf"
                  protected $iLineNo =>
                  int(5)
                }
                protected $iLineNo =>
                int(5)
              }
              private $bIsImportant =>
              bool(false)
              protected $iLineNo =>
              int(5)
            }
          }
        }
        protected $iLineNo =>
        int(3)
      }
      [2] =>
      class Sabberworm\CSS\RuleSet\DeclarationBlock#13 (3) {
        private $aSelectors =>
        array(2) {
          [0] =>
          class Sabberworm\CSS\Property\Selector#14 (2) {
            private $sSelector =>
            string(4) "html"
            private $iSpecificity =>
            NULL
          }
          [1] =>
          class Sabberworm\CSS\Property\Selector#15 (2) {
            private $sSelector =>
            string(4) "body"
            private $iSpecificity =>
            NULL
          }
        }
        private $aRules =>
        array(1) {
          'font-size' =>
          array(1) {
            [0] =>
            class Sabberworm\CSS\Rule\Rule#16 (4) {
              private $sRule =>
              string(9) "font-size"
              private $mValue =>
              class Sabberworm\CSS\Value\Size#17 (4) {
                private $fSize =>
                double(1.6)
                private $sUnit =>
                string(2) "em"
                private $bIsColorComponent =>
                bool(false)
                protected $iLineNo =>
                int(9)
              }
              private $bIsImportant =>
              bool(false)
              protected $iLineNo =>
              int(9)
            }
          }
        }
        protected $iLineNo =>
        int(8)
      }
      [3] =>
      class Sabberworm\CSS\CSSList\KeyFrame#18 (4) {
        private $vendorKeyFrame =>
        string(9) "keyframes"
        private $animationName =>
        string(6) "mymove"
        protected $aContents =>
        array(2) {
          [0] =>
          class Sabberworm\CSS\RuleSet\DeclarationBlock#19 (3) {
            private $aSelectors =>
            array(1) {
              [0] =>
              class Sabberworm\CSS\Property\Selector#20 (2) {
                private $sSelector =>
                string(4) "from"
                private $iSpecificity =>
                NULL
              }
            }
            private $aRules =>
            array(1) {
              'top' =>
              array(1) {
                [0] =>
                class Sabberworm\CSS\Rule\Rule#21 (4) {
                  private $sRule =>
                  string(3) "top"
                  private $mValue =>
                  class Sabberworm\CSS\Value\Size#22 (4) {
                    private $fSize =>
                    double(0)
                    private $sUnit =>
                    string(2) "px"
                    private $bIsColorComponent =>
                    bool(false)
                    protected $iLineNo =>
                    int(13)
                  }
                  private $bIsImportant =>
                  bool(false)
                  protected $iLineNo =>
                  int(13)
                }
              }
            }
            protected $iLineNo =>
            int(13)
          }
          [1] =>
          class Sabberworm\CSS\RuleSet\DeclarationBlock#23 (3) {
            private $aSelectors =>
            array(1) {
              [0] =>
              class Sabberworm\CSS\Property\Selector#24 (2) {
                private $sSelector =>
                string(2) "to"
                private $iSpecificity =>
                NULL
              }
            }
            private $aRules =>
            array(1) {
              'top' =>
              array(1) {
                [0] =>
                class Sabberworm\CSS\Rule\Rule#25 (4) {
                  private $sRule =>
                  string(3) "top"
                  private $mValue =>
                  class Sabberworm\CSS\Value\Size#26 (4) {
                    private $fSize =>
                    double(200)
                    private $sUnit =>
                    string(2) "px"
                    private $bIsColorComponent =>
                    bool(false)
                    protected $iLineNo =>
                    int(14)
                  }
                  private $bIsImportant =>
                  bool(false)
                  protected $iLineNo =>
                  int(14)
                }
              }
            }
            protected $iLineNo =>
            int(14)
          }
        }
        protected $iLineNo =>
        int(12)
      }
    }
    protected $iLineNo =>
    int(1)
  }
  
  ```
  </details>
  
  #### Output (`render()`)
  
  ```css
  @charset "utf-8";
  @font-face {font-family: "CrassRoots";src: url("../media/cr.ttf");}
  html, body {font-size: 1.6em;}
  @keyframes mymove {from {top: 0px;} to {top: 200px;}}
  ```
  
  ### Example 2 (Values)
  
  #### Input
  
  ```css
  #header {
      margin: 10px 2em 1cm 2%;
      font-family: Verdana, Helvetica, "Gill Sans", sans-serif;
      color: red !important;
  }
  
  ```
  
  <details>
    <summary><b>Structure (<code>var_dump()</code>)</b></summary>
  
  ```php
  class Sabberworm\CSS\CSSList\Document#4 (2) {
    protected $aContents =>
    array(1) {
      [0] =>
      class Sabberworm\CSS\RuleSet\DeclarationBlock#5 (3) {
        private $aSelectors =>
        array(1) {
          [0] =>
          class Sabberworm\CSS\Property\Selector#6 (2) {
            private $sSelector =>
            string(7) "#header"
            private $iSpecificity =>
            NULL
          }
        }
        private $aRules =>
        array(3) {
          'margin' =>
          array(1) {
            [0] =>
            class Sabberworm\CSS\Rule\Rule#7 (4) {
              private $sRule =>
              string(6) "margin"
              private $mValue =>
              class Sabberworm\CSS\Value\RuleValueList#12 (3) {
                protected $aComponents =>
                array(4) {
                  [0] =>
                  class Sabberworm\CSS\Value\Size#8 (4) {
                    private $fSize =>
                    double(10)
                    private $sUnit =>
                    string(2) "px"
                    private $bIsColorComponent =>
                    bool(false)
                    protected $iLineNo =>
                    int(2)
                  }
                  [1] =>
                  class Sabberworm\CSS\Value\Size#9 (4) {
                    private $fSize =>
                    double(2)
                    private $sUnit =>
                    string(2) "em"
                    private $bIsColorComponent =>
                    bool(false)
                    protected $iLineNo =>
                    int(2)
                  }
                  [2] =>
                  class Sabberworm\CSS\Value\Size#10 (4) {
                    private $fSize =>
                    double(1)
                    private $sUnit =>
                    string(2) "cm"
                    private $bIsColorComponent =>
                    bool(false)
                    protected $iLineNo =>
                    int(2)
                  }
                  [3] =>
                  class Sabberworm\CSS\Value\Size#11 (4) {
                    private $fSize =>
                    double(2)
                    private $sUnit =>
                    string(1) "%"
                    private $bIsColorComponent =>
                    bool(false)
                    protected $iLineNo =>
                    int(2)
                  }
                }
                protected $sSeparator =>
                string(1) " "
                protected $iLineNo =>
                int(2)
              }
              private $bIsImportant =>
              bool(false)
              protected $iLineNo =>
              int(2)
            }
          }
          'font-family' =>
          array(1) {
            [0] =>
            class Sabberworm\CSS\Rule\Rule#13 (4) {
              private $sRule =>
              string(11) "font-family"
              private $mValue =>
              class Sabberworm\CSS\Value\RuleValueList#15 (3) {
                protected $aComponents =>
                array(4) {
                  [0] =>
                  string(7) "Verdana"
                  [1] =>
                  string(9) "Helvetica"
                  [2] =>
                  class Sabberworm\CSS\Value\CSSString#14 (2) {
                    private $sString =>
                    string(9) "Gill Sans"
                    protected $iLineNo =>
                    int(3)
                  }
                  [3] =>
                  string(10) "sans-serif"
                }
                protected $sSeparator =>
                string(1) ","
                protected $iLineNo =>
                int(3)
              }
              private $bIsImportant =>
              bool(false)
              protected $iLineNo =>
              int(3)
            }
          }
          'color' =>
          array(1) {
            [0] =>
            class Sabberworm\CSS\Rule\Rule#16 (4) {
              private $sRule =>
              string(5) "color"
              private $mValue =>
              string(3) "red"
              private $bIsImportant =>
              bool(true)
              protected $iLineNo =>
              int(4)
            }
          }
        }
        protected $iLineNo =>
        int(1)
      }
    }
    protected $iLineNo =>
    int(1)
  }
  
  ```
  </details>
  
  #### Output (`render()`)
  
  ```css
  #header {margin: 10px 2em 1cm 2%;font-family: Verdana,Helvetica,"Gill Sans",sans-serif;color: red !important;}
  ```
  
  ## Contributors/Thanks to
  
  * [oliverklee](https://github.com/oliverklee) for lots of refactorings, code modernizations and CI integrations
  * [raxbg](https://github.com/raxbg) for contributions to parse `calc`, grid lines, and various bugfixes.
  * [westonruter](https://github.com/westonruter) for bugfixes and improvements.
  * [FMCorz](https://github.com/FMCorz) for many patches and suggestions, for being able to parse comments and IE hacks (in lenient mode).
  * [Lullabot](https://github.com/Lullabot) for a patch that allows to know the line number for each parsed token.
  * [ju1ius](https://github.com/ju1ius) for the specificity parsing code and the ability to expand/compact shorthand properties.
  * [ossinkine](https://github.com/ossinkine) for a 150 time performance boost.
  * [GaryJones](https://github.com/GaryJones) for lots of input and [https://css-specificity.info/](https://css-specificity.info/).
  * [docteurklein](https://github.com/docteurklein) for output formatting and `CSSList->remove()` inspiration.
  * [nicolopignatelli](https://github.com/nicolopignatelli) for PSR-0 compatibility.
  * [diegoembarcadero](https://github.com/diegoembarcadero) for keyframe at-rule parsing.
  * [goetas](https://github.com/goetas) for @namespace at-rule support.
  * [View full list](https://github.com/sabberworm/PHP-CSS-Parser/contributors)
  
  ## Misc
  
  * Legacy Support: The latest pre-PSR-0 version of this project can be checked with the `0.9.0` tag.
  * Running Tests: To run all unit tests for this project, run `composer install` to install phpunit and use `./vendor/bin/phpunit`.