|
2 | 2 |
|
3 | 3 | QueryPath is a jQuery-like library for working with XML and HTML(5) documents in PHP. It is stable software, [with the original library garnering 4M+ downloads](https://packagist.org/packages/querypath/querypath) since first published in 2009. |
4 | 4 |
|
5 | | -**⚠️ This is a fork of a fork. The [original library](https://github.com/technosophos/querypath), and [subsequent fork](https://github.com/arthurkushman/querypath), are no longer being maintained. The aim of `gravitypdf/querypath` is to ensure the library remains compatible with the latest version of PHP, and bug free. 🧑💻There is still a lot of legacy code to clean up + modernize, and any assistance given is appreciated.** |
| 5 | +**This is a fork of a fork. The [original library](https://github.com/technosophos/querypath), and [subsequent fork](https://github.com/arthurkushman/querypath), are no longer being maintained. The aim of `gravitypdf/querypath` is to ensure the library remains compatible with the latest version of PHP, and bug free. 🧑💻There is still a lot of legacy code to clean up + modernize, and any assistance given is appreciated.** |
| 6 | + |
| 7 | +> If you are viewing this file on QueryPath GitHub repository homepage or on Packagist, please note that the default repository branch is `main` which can differ from the last stable release. |
6 | 8 |
|
7 | 9 | [](https://packagist.org/packages/gravitypdf/querypath) |
8 | 10 | [](https://packagist.org/packages/gravitypdf/querypath) |
9 | 11 | [](https://packagist.org/packages/gravitypdf/querypath) |
10 | 12 |
|
11 | | -> ⚠ If you are viewing this file on QueryPath GitHub repository homepage or on Packagist, please note that the default repository branch is `main` which can differ from the last stable release. |
12 | | -
|
13 | 13 | ## Installation |
14 | 14 | ``` |
15 | 15 | composer require gravitypdf/querypath |
16 | 16 | ``` |
17 | 17 |
|
18 | 18 | ## Basic Usage |
19 | 19 |
|
20 | | -You can parse documents like this: |
| 20 | +To parse HTML or XML: |
21 | 21 |
|
22 | 22 | ```php |
23 | 23 | <?php |
24 | 24 | // Assuming you installed from Composer: |
25 | | -require 'vendor/autoload.php'; |
26 | | - |
27 | | -// HTML5 |
28 | | -$qp = html5qp('path/to/file.html'); |
29 | | - |
30 | | -// Legacy HTML via libxml |
31 | | -$qp = htmlqp('path/to/file.html'); |
| 25 | +require_once __DIR__.'/vendor/autoload.php'; |
| 26 | + |
| 27 | +try { |
| 28 | + // Recommended: uses the masterminds/html5 library to process the HTML |
| 29 | + $qp = html5qp(__DIR__.'/path/to/file.html'); // load a file from disk |
| 30 | + $qp = html5qp('<div>You can pass a string of HTML directly to the function</div>'); // load a string |
| 31 | +} catch (\QueryPath\Exception $e) { |
| 32 | + // Handle error |
| 33 | +} |
32 | 34 |
|
33 | | -// XML or XHTML |
34 | | -$qp = qp('path/to/file.html'); |
| 35 | +try { |
| 36 | + // Legacy: uses libxml to parse HTML |
| 37 | + $qp = htmlqp(__DIR__.'/path/to/file.html'); // load a file from disk |
| 38 | + $qp = htmlqp('<div>You can pass a string of HTML directly to the function</div>'); // load a string |
| 39 | +} catch (\QueryPath\Exception $e) { |
| 40 | + // Handle error |
| 41 | +} |
35 | 42 |
|
36 | | -// All of the above can take string markup instead of a file name: |
37 | | -$qp = qp('<?xml version='1.0'?><hello><world/></hello>') |
| 43 | +try { |
| 44 | + // XML or XHTML |
| 45 | + $qp = qp(__DIR__.'/path/to/file.html'); // load a file from disk |
| 46 | + $qp = qp("<?xml version='1.0'?><hello><world/></hello>"); // load a string |
| 47 | +} catch (\QueryPath\Exception $e) { |
| 48 | + // Handle error |
| 49 | +} |
38 | 50 | ``` |
39 | 51 |
|
40 | | -The real power of QueryPath comes from chaining methods together: |
| 52 | +The real power of QueryPath comes from chaining methods together. This example will generate a valid HTML5 document and output to the browser: |
41 | 53 |
|
42 | 54 | ```php |
43 | | -require 'vendor/autoload.php'; |
44 | | - |
45 | | -html5qp(\QueryPath\QueryPath::HTML5_STUB, 'title') |
46 | | - // Add some text to the title |
47 | | - ->text('Example of QueryPath.') |
48 | | - // Now look for the <body> element |
49 | | - ->top('body') |
50 | | - // Inside the body, add a title and paragraph. |
51 | | - ->append('<h1>This is a test page</h1><p>Test text</p>') |
52 | | - // Now we select the paragraph we just created inside the body |
53 | | - ->children('p') |
54 | | - // Add a 'class="some-class"' attribute to the paragraph |
55 | | - ->attr('class', 'some-class') |
56 | | - // And add a style attribute, too, setting the background color. |
57 | | - ->css('background-color', '#eee') |
58 | | - // Now go back to the paragraph again |
59 | | - ->parent() |
60 | | - // Before the paragraph and the title, add an empty table. |
61 | | - ->prepend('<table id="my-table"></table>') |
62 | | - // Now let's go to the table... |
63 | | - ->top('#my-table') |
64 | | - // Add a couple of empty rows |
65 | | - ->append('<tr></tr><tr></tr>') |
66 | | - // select the rows (both at once) |
67 | | - ->children() |
68 | | - // Add a CSS class to both rows |
69 | | - ->addClass('table-row') |
70 | | - // Now just get the first row (at position 0) |
71 | | - ->eq(0) |
72 | | - // Add a table header in the first row |
73 | | - ->append('<th>This is the header</th>') |
74 | | - // Now go to the next row |
75 | | - ->next() |
76 | | - // Add some data to this row |
77 | | - ->append('<td>This is the data</td>') |
78 | | - // Write it all out as HTML |
79 | | - ->writeHTML5(); |
| 55 | +try { |
| 56 | + html5qp(\QueryPath\QueryPath::HTML5_STUB, 'title') |
| 57 | + // Add some text to the title |
| 58 | + ->text('Example of QueryPath.') |
| 59 | + // Now look for the <body> element |
| 60 | + ->top('body') |
| 61 | + // Inside the body, add a title and paragraph. |
| 62 | + ->append('<h1>This is a test page</h1><p>Test text</p>') |
| 63 | + // Now we select the paragraph we just created inside the body |
| 64 | + ->children('p') |
| 65 | + // Add a 'class="some-class"' attribute to the paragraph |
| 66 | + ->attr('class', 'some-class') |
| 67 | + // And add a style attribute, too, setting the background color. |
| 68 | + ->css('background-color', '#eee') |
| 69 | + // Now go back to the paragraph again |
| 70 | + ->parent() |
| 71 | + // Before the paragraph and the title, add an empty table. |
| 72 | + ->prepend('<table id="my-table"></table>') |
| 73 | + // Now let's go to the table... |
| 74 | + ->top('#my-table') |
| 75 | + // Add a couple of empty rows |
| 76 | + ->append('<tr></tr><tr></tr>') |
| 77 | + // select the rows (both at once) |
| 78 | + ->children() |
| 79 | + // Add a CSS class to both rows |
| 80 | + ->addClass('table-row') |
| 81 | + // Now just get the first row (at position 0) |
| 82 | + ->eq(0) |
| 83 | + // Add a table header in the first row |
| 84 | + ->append('<th>This is the header</th>') |
| 85 | + // Now go to the next row |
| 86 | + ->next() |
| 87 | + // Add some data to this row |
| 88 | + ->append('<td>This is the data</td>') |
| 89 | + // Write it all out as HTML |
| 90 | + ->writeHTML5(); |
| 91 | +} catch (\QueryPath\Exception $e) { |
| 92 | + // Handle error |
| 93 | +} |
80 | 94 | ``` |
81 | 95 |
|
82 | | -You can also search for specific elements and loop over any matches: |
| 96 | +You can find specific nodes, loop over the matches, and extract information about each element: |
83 | 97 |
|
84 | 98 | ```php |
85 | | -$html = ' |
86 | | -<ul> |
87 | | - <li>Foo</li> |
88 | | - <li>Bar</li> |
89 | | - <li>FooBar</li> |
90 | | -</ul>'; |
91 | | - |
92 | | -$qp = html5qp($html); |
93 | | -foreach ($qp->find('li') as $li) { |
94 | | - echo $li->text() .'<br>'; |
| 99 | +try { |
| 100 | + $html = ' |
| 101 | + <ul> |
| 102 | + <li>Foo</li> |
| 103 | + <li>Bar</li> |
| 104 | + <li>FooBar</li> |
| 105 | + </ul>'; |
| 106 | + |
| 107 | + $qp = html5qp($html); |
| 108 | + foreach ($qp->find('li') as $li) { |
| 109 | + echo $li->text() .'<br>'; |
| 110 | + } |
| 111 | +} catch (\QueryPath\Exception $e) { |
| 112 | + // Handle error |
95 | 113 | } |
96 | 114 | ``` |
97 | 115 |
|
98 | | -See the [examples directory files](https://github.com/GravityPDF/querypath/tree/main/examples) for more usages of QueryPath. |
| 116 | +See the [examples directory files](https://github.com/GravityPDF/querypath/tree/main/examples) for more usages. |
99 | 117 |
|
100 | 118 | ## Online Manual |
101 | 119 |
|
102 | 120 | The legacy QueryPath manual has been automatically generated from inline DocBlocks using phpDocumentor, and can be found at [http://querypath.org](http://querypath.org/). |
103 | 121 |
|
104 | | -> ⚠️ Note: The website querypath.org is not built or maintained by Gravity PDF, and we have no access to manage or change anything. [Help is wanted writing new documentation in the repo's Wiki](https://github.com/GravityPDF/querypath/wiki). |
| 122 | +> ⚠️ querypath.org is not built or maintained by Gravity PDF, and we have no access to manage or change the website. [Help writing new documentation in the repo's Wiki is wanted](https://github.com/GravityPDF/querypath/wiki). |
105 | 123 |
|
106 | 124 | ## General Troubleshooting |
107 | 125 |
|
|
0 commit comments