Download the PHP package wikimedia/zest-css without Composer
On this page you can find all versions of the php package wikimedia/zest-css. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Download wikimedia/zest-css
More information about wikimedia/zest-css
Files in wikimedia/zest-css
Package zest-css
Short Description Fast, lightweight, extensible CSS selector engine for PHP
License MIT
Homepage https://www.mediawiki.org/wiki/Zest
Informations about the package zest-css
zest.php
zest.php is a fast, lightweight, extensible CSS selector engine for PHP.
Zest was designed to be very concise while still supporting CSS3/CSS4 selectors and remaining fast.
This is a port to PHP of the zest.js selector library. Since that project hasn't been updated in a while, bugfixes have been taken from the copy of zest included in the domino DOM library.
Report issues on Phabricator.
Usage
Install
This package is available on Packagist:
API
Functions below which take an opts
array can be passed additional options
which affect match results. This are available from within custom selectors
(see below). At the moment, the standard selectors support the following
options:
standardsMode
(bool
): if present and true, various PHP workarounds will be disabled in favor of calling methods defined in web standards.getElementsById
(true|callable(DOMNode,string):array<DOMElement>
): if set totrue
then an optimization will be disabled to ensure that Zest can return multiple elements for ID selectors if IDs are not unique in the document. If set to acallable
that takes a context node and an ID string and returns an array of Elements, a third-party DOM implementation can support an efficient index allowing multiple elements to share the same ID.
All methods will throw the exception returned by
ZestInst::newBadSelectorException()
(by default, a new
InvalidArgumentException
) if the selector fails to parse.
Zest::find( string $selector, $context, array $opts = [] ): array
This is equivalent to the standard
DOM method ParentNode#querySelectorAll()
.
Zest::matches( $element, string $selector, array $opts = [] ): bool
This is equivalent to the standard
DOM method Element#matches()
.
Since the PHP implementations of
DOMDocument::getElementById
and
DOMDocument#getElementsByTagName
have some performance and spec-compliance issues, Zest also exports useful
performant and correct versions of these:
Zest::getElementsById( $contextNode, string $id, array $opts = [] ): array
This is equivalent to the standard DOM method
Document#getElementById()
(although you can use any context node, not just the top-level document).
In addition, with the proper support from the DOM implementation, this can
return more than one matching element.
Zest::getElementsByTagName( $contextNode, string $tagName, array $opts = [] ): array
This is equivalent to the standard DOM method Element#getElementsByTagName()
,
although you can use a DocumentFragment
as the $contextNode
.
Extension
It is possible to add your own selectors, operators, or combinators.
These are added to an instance of ZestInst
, so they don't affect other
instances of Zest or the static Zest::find
/Zest::matches
methods.
The ZestInst
class has non-static versions of all the static methods
available on Zest
.
Adding a simple selector
Adding simple selectors is fairly straight forward. Only the addition of pseudo classes and attribute operators is possible. (Adding your own "style" of selector would require changes to the core logic.)
Here is an example of a custom :name
selector which will match for an
element's name
attribute: e.g. h1:name(foo)
. Effectively an alias
for h1[name=foo]
.
If you wish to add selectors which depend on global properties (such as
:target
) you can add the global information to $opts
and it will be
made available when your selector function is called.
NOTE: if your pseudo-class does not take a parameter, use addSelector0
.
Adding an attribute operator
Adding a combinator
Adding a combinator is a bit trickier. It may seem confusing at first because the logic is upside-down. Zest interprets selectors from right to left.
Here is an example how a parent combinator could be implemented:
The $test
function tests whatever simple selectors it needs to look for, but
it isn't important what it does. The most important part is that you return
the relevant element once it's found.
Tests
License and Credits
The original zest codebase is (c) Copyright 2011-2012, Christopher Jeffrey.
The port to PHP was initially done by C. Scott Ananian and is (c) Copyright 2019 Wikimedia Foundation.
Additional code and functionality is (c) Copyright 2020-2021 Wikimedia Foundation.
Both the original zest codebase and this port are distributed under the MIT license; see LICENSE for more info.
All versions of zest-css with dependencies
ext-mbstring Version *
ext-xml Version *