Skip to content

Commit 5856b42

Browse files
Oleksii ShatrovReset
Oleksii Shatrov
authored and
Reset
committed
1.0.0-RC1
0 parents  commit 5856b42

File tree

86 files changed

+2304
-0
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

86 files changed

+2304
-0
lines changed

‎.github/workflows/ci.yml‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
name: CI
2+
3+
on:
4+
push:
5+
branches:
6+
- master
7+
pull_request:
8+
branches:
9+
- master
10+
11+
jobs:
12+
test:
13+
runs-on: ubuntu-latest
14+
15+
steps:
16+
- name: Check out repository code
17+
uses: actions/checkout@v3
18+
19+
- name: Set up PHP
20+
uses: shivammathur/setup-php@v2
21+
with:
22+
php-version: '8.1' # Specify your PHP version
23+
extensions: mbstring, dom, json # Add any other necessary extensions
24+
25+
- name: Install dependencies
26+
run: composer install --prefer-dist --no-progress --no-suggest
27+
28+
- name: Run tests
29+
run: ./vendor/bin/phpunit --testdox
30+
31+
- name: Run PHP compability test
32+
run: ./vendor/bin/phpcs --config-set installed_paths vendor/phpcompatibility/php-compatibility && ./vendor/bin/phpcs --standard=PHPCompatibility --runtime-set testVersion 8.1 ./src
33+
34+
- name: Run PSR compability test
35+
run: ./vendor/bin/phpcs --standard=PSR12 --exclude=Generic.Files.LineLength ./src ./tests

‎.gitignore‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
/vendor/
2+
composer.lock
3+
.phpunit.result.cache
4+
.idea

‎DEMO_RUN_SEQUENCE.md‎

Lines changed: 94 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,94 @@
1+
```php
2+
3+
require_once('vendor/autoload.php');
4+
5+
const API_URL = 'http://0.0.0.0:9091/API';
6+
const PASSWORD = 'your-password';
7+
8+
$aparser = new \ResetButton\AparserPhpClient\Aparser(API_URL,PASSWORD);
9+
$parser = new \ResetButton\AparserPhpClient\Parser("Net::HTTP");
10+
$parser->addOverride("useproxy", false);
11+
$parser->addOverride("formatresult", '$code');
12+
13+
echo "A-parser demo run sequence start".lineBreak().lineBreak();
14+
15+
$action = new \ResetButton\AparserPhpClient\Actions\PingAction();
16+
renderResult($aparser, $action);
17+
18+
$action = new \ResetButton\AparserPhpClient\Actions\InfoAction();
19+
renderResult($aparser, $action);
20+
21+
$action = new \ResetButton\AparserPhpClient\Actions\GetParserPresetAction($parser);
22+
renderResult($aparser, $action);
23+
24+
$action = new \ResetButton\AparserPhpClient\Actions\GetProxiesAction();
25+
renderResult($aparser, $action);
26+
27+
$action = new \ResetButton\AparserPhpClient\Actions\GetProxiesAction();
28+
renderResult($aparser, $action);
29+
30+
$action = new \ResetButton\AparserPhpClient\Actions\GetTasksListAction();
31+
renderResult($aparser, $action);
32+
33+
$action = new \ResetButton\AparserPhpClient\Actions\GetParserInfoAction($parser);
34+
renderResult($aparser, $action);
35+
36+
//This method will break a-parser, if you have 0 accounts in base
37+
//$action = new \ResetButton\AparserPhpClient\Actions\GetAccountsCountAction();
38+
//renderResult($aparser, $action);
39+
40+
$action = new \ResetButton\AparserPhpClient\Actions\ChangeProxyCheckerStateAction("default", true);
41+
renderResult($aparser, $action);
42+
43+
//Requests
44+
$action = new \ResetButton\AparserPhpClient\Actions\OneRequestAction($parser, "https://a-parser.com");
45+
renderResult($aparser, $action);
46+
47+
$action = new \ResetButton\AparserPhpClient\Actions\BulkRequestAction($parser, ["https://a-parser.com"]);
48+
renderResult($aparser, $action);
49+
50+
//Task
51+
$parser->addOverride('requestdelay', 15);
52+
$action = \ResetButton\AparserPhpClient\Actions\AddTaskAction::withParser($parser, ["https://a-parser.com"]);
53+
54+
/* @var int $taskNumber */
55+
$taskNumber = $aparser->runAction($action);
56+
echo $action::NAME.": ".json_encode($taskNumber).lineBreak().lineBreak();
57+
58+
$action = new ResetButton\AparserPhpClient\Actions\MoveTaskAction($taskNumber, \ResetButton\AparserPhpClient\Enums\MoveTaskDirection::START);
59+
renderResult($aparser, $action);
60+
61+
$action = new ResetButton\AparserPhpClient\Actions\GetTaskConfAction($taskNumber);
62+
renderResult($aparser, $action);
63+
64+
$action = new ResetButton\AparserPhpClient\Actions\GetTaskStateAction([$taskNumber]);
65+
////Wait task for complete
66+
do {
67+
sleep(1);
68+
$taskStateResult = $aparser->runAction($action);
69+
echo $action::NAME.": ".$taskStateResult[0]['status'].lineBreak();
70+
} while ($taskStateResult[0]['status'] != "completed");
71+
echo lineBreak();
72+
73+
$action = new ResetButton\AparserPhpClient\Actions\GetTaskResultsFileAction($taskNumber);
74+
renderResult($aparser, $action);
75+
76+
$action = new ResetButton\AparserPhpClient\Actions\DeleteTaskResultsFileAction($taskNumber);
77+
renderResult($aparser, $action);
78+
79+
$action = new ResetButton\AparserPhpClient\Actions\ChangeTaskStatusAction($taskNumber, \ResetButton\AparserPhpClient\Enums\ChangeableTaskStatus::DELETING);
80+
renderResult($aparser, $action);
81+
82+
echo "A-parser demo run sequence end".lineBreak().lineBreak();
83+
84+
function renderResult(\ResetButton\AparserPhpClient\Aparser $aparser, \ResetButton\AparserPhpClient\Actions\Action $action)
85+
{
86+
$result = $aparser->runAction($action);
87+
echo $action::NAME.": ".json_encode($result).lineBreak().lineBreak();
88+
}
89+
90+
function lineBreak() : string
91+
{
92+
return (PHP_SAPI === 'cli') ? PHP_EOL : '<br />';
93+
}
94+
```

‎LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2024 Oleksii Shatrov
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎README.md‎

Lines changed: 173 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,173 @@
1+
# A-Aparser PHP API
2+
This A-parser PHP API library provides convenient access to the [A-Parser HTTP API](https://en.a-parser.com/docs/api/overview).
3+
4+
## Requirements
5+
- php >= 8.1
6+
- guzzlehttp/guzzle >= 7.0
7+
8+
## Installation
9+
```shell
10+
composer require reset-button/a-parser-php-client
11+
```
12+
13+
## Quickstart
14+
```php
15+
//Define an a-parser instance
16+
$aparser = new \ResetButton\AparserPhpClient\Aparser('http://full_url_to_api_endpoint','password');
17+
18+
//Define an action from https://en.a-parser.com/docs/api/methods
19+
$taskConfAction = new \ResetButton\AparserPhpClient\Actions\GetTaskConfAction(1);
20+
21+
//Run the action and get the result
22+
$result = $aparser->runAction($action);
23+
```
24+
## Usage
25+
### Basic Action Usage
26+
Define an A-parser instance, passing full URL to API endpoint and password
27+
```php
28+
//Define an a-parser instance
29+
$aparser = new \ResetButton\AparserPhpClient\Aparser('full_url_to_api_endpoint','password');
30+
```
31+
Instantiate an action using the appropriate action class, as outlined in the official documentation
32+
```php
33+
$taskConfAction = new \ResetButton\AparserPhpClient\Actions\GetTaskConfAction(1);
34+
```
35+
Run the action by calling `runAction` method
36+
```php
37+
$result = $aparser->runAction($action);
38+
```
39+
### Using Parser class in Actions
40+
41+
All actions that accept parser name and config as parameter, accept a `Parser` instance instead (addTask, oneRequest, bulkRequest, getParserPreset, getParserInfo)
42+
43+
`Parser` class contains all logic, related to used parser in API methods, that used it
44+
45+
![Parser class logic](./docs/parser.png)
46+
47+
In minimal approach you need only to create `Parser` instance without any configuration and pass it to corresponding method
48+
49+
```php
50+
$parser = new \ResetButton\AparserPhpClient\Parser('HTML::EmailExtractor','parser preset, if differs from default');
51+
$action = new \ResetButton\AparserPhpClient\Actions\GetParserInfoAction($parser);
52+
```
53+
54+
You can configure parser with options, overrides, etc before passing it to action by calling corresponding methods
55+
```php
56+
$parser->addOption('parseLevel', '1', ["limit" => 0]);
57+
$parser->addOverride('useproxy', false);
58+
```
59+
60+
Or you can set full configuration at once using a corresponding method, this is useful when copy pasting from API request
61+
62+
<img src="./docs/setConfiguration.png" alt="drawing" height="500"/>
63+
64+
```php
65+
$parser->setConfiguration([
66+
[
67+
"type" => "options",
68+
"id" => "parseLevel",
69+
"value" => 1,
70+
"additional" => [
71+
"limit" => "0"
72+
]
73+
],
74+
[
75+
"type" => "override",
76+
"id" => "useproxy",
77+
"value" => true
78+
]
79+
]);
80+
```
81+
> Note, that parser configuration has no effect in `getParserPreset` and `getParserInfo` actions.
82+
83+
### Configuring Actions
84+
85+
All action required parameters are configured via constructor, and optional are set using builder pattern with corresponding parameters from the documentations with "set" prefix, for example
86+
```php
87+
//Example 1
88+
$action = new \ResetButton\AparserPhpClient\Actions\GetProxiesAction();
89+
$action->setCheckers(['premium']); //set checkers parameter
90+
91+
//Example 2
92+
$parser = new \ResetButton\AparserPhpClient\Parser('HTML::EmailExtractor','parser preset, if differs from default');
93+
$action = new \ResetButton\AparserPhpClient\Actions\OneRequestAction($parser,'https://a-parser.com');
94+
$action->setRawResults(true);
95+
$action->setDoLog(false);
96+
```
97+
#### Configuring `addTask` action
98+
This method is differs from others methods, it can be instantiated via passing at least one parser or passing a [previously saved preset](https://a-parser.com/docs/api/methods#starting-a-previously-saved-task), this two methods are implemented via named constructor
99+
100+
```php
101+
$parser = new \ResetButton\AparserPhpClient\Parser('HTML::EmailExtractor');
102+
$actionViaParser = \ResetButton\AparserPhpClient\Actions\AddTaskAction::withParser($parser, ['query1']);
103+
$actionViaPreset = \ResetButton\AparserPhpClient\Actions\AddTaskAction::withPreset('savedPreset', ['query1']);
104+
```
105+
Also, `addTask` action is a most complex action in API, so many setters for are not implemented and you should use `setDataValue` from Action Direct Methods to set parameters
106+
```php
107+
$actionViaPreset = \ResetButton\AparserPhpClient\Actions\AddTaskAction::withPreset('savedPreset', ['query1']);
108+
$actionViaPreset->setResultsUnique(); //Use setter
109+
$actionViaPreset->setDataValue("saveFailedQueries", true); //Setter for this option is missing, using direct method
110+
```
111+
##### Setting queries source
112+
You should pass queries when creating action, no matter the source. And then change queries source using `setQueriesFrom...` methods, default behavior is from **text**.
113+
114+
```php
115+
$fromText = \ResetButton\AparserPhpClient\Actions\AddTaskAction::withPreset('savedPreset', ['query1', 'query1']);
116+
117+
$fromFile = \ResetButton\AparserPhpClient\Actions\AddTaskAction::withPreset('savedPreset', ['filename1.txt', 'filename2.txt']);
118+
$fromFile->setQueriesFromFiles();
119+
120+
//If you need change source again to text use
121+
// $fromFile->setQueriesFromText();
122+
```
123+
124+
#### Action Direct Methods
125+
126+
You can read any configuration option using `getDataValue` helper, if this option is not exists - null will returned
127+
```php
128+
$taskConfAction = new \ResetButton\AparserPhpClient\Actions\GetTaskConfAction(1);
129+
$taskConfAction->getDataValue("taskUid"); //will return 1
130+
$taskConfAction->getDataValue("taskWrongUid"); //will return null
131+
```
132+
You can directly set/overwrite any configuration option using `setDataValue` helper. Use with caution.
133+
```php
134+
$taskConfAction = new \ResetButton\AparserPhpClient\Actions\GetTaskConfAction(1);
135+
$taskConfAction->setDataValue("taskUid", 10);
136+
$taskConfAction->getDataValue("taskUid"); //will return 10
137+
```
138+
You can get all full configuration options using `getData` helper.
139+
```php
140+
$parser = new \ResetButton\AparserPhpClient\Parser("SE::Google")
141+
$parserPresetAction = new \ResetButton\AparserPhpClient\Actions\GetTaskConfAction($parser);
142+
$taskConfAction->getData(); //will return ["parser" => "SE::Google", "preset": "default"]
143+
```
144+
145+
### Aparser methods
146+
147+
Instantiate A-parser instance by passing URL to API endpoint and password
148+
```php
149+
$aparser = new \ResetButton\AparserPhpClient\Aparser('http://full_url_to_api_endpoint','password');
150+
```
151+
Prepare actions and run it by calling `runAction` method
152+
```php
153+
$pingAction = new \ResetButton\AparserPhpClient\Actions\PingAction();
154+
$getProxiesAction = new \ResetButton\AparserPhpClient\Actions\GetProxiesAction();
155+
$resultPing = $aparser->runAction($pingAction);
156+
$resultGetProxies = $aparser->runAction($getProxiesAction);
157+
````
158+
`runAction` will return `data` section from A-parser success response payload or throw a `AparserApiException` if A-parser responds with error
159+
160+
You can get JSON string from passed action using `getJsonString` helper.
161+
```php
162+
$aparser->getJsonString($getPingAction); //will return something like {"password": "pass","action": "ping"}
163+
```
164+
165+
At last, you can just copy JSON query from A-parser and send it via API directly even ignoring previously passed password
166+
```php
167+
$jsonString = '{ "password": "pass", "action": "ping" }';
168+
$aparser->runJsonString($jsonString);
169+
```
170+
171+
## License
172+
173+
This package is open-sourced software licensed under the [MIT license](https://opensource.org/licenses/MIT).

‎composer.json‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
{
2+
"name": "reset-button/a-parser-php-client",
3+
"description": "PHP client for A-Parser API",
4+
"type": "library",
5+
"version": "1.0.0-RC1",
6+
"license": "MIT",
7+
"autoload": {
8+
"psr-4": {
9+
"ResetButton\\AparserPhpClient\\": "src/"
10+
}
11+
},
12+
"autoload-dev": {
13+
"psr-4": {
14+
"Tests\\": "tests/"
15+
}
16+
},
17+
"authors": [
18+
{
19+
"name": "Alexey Shatrov",
20+
"email": "[email protected]"
21+
}
22+
],
23+
"minimum-stability": "RC",
24+
"prefer-stable": true,
25+
"require": {
26+
"php" : "^8.1",
27+
"guzzlehttp/guzzle" : "^7.0"
28+
},
29+
"require-dev": {
30+
"phpunit/phpunit": "^10.0",
31+
"squizlabs/php_codesniffer": "^3.11",
32+
"phpcompatibility/php-compatibility": "^9.3"
33+
},
34+
"homepage": "https://github.com/reset-button/a-parser-php-client",
35+
"keywords": ["a-parser", "php", "client", "api"]
36+
}

‎docs/parser.png‎

194 KB
Loading

‎docs/setConfiguration.png‎

125 KB
Loading

‎phpunit.xml‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
<phpunit bootstrap="vendor/autoload.php">
2+
<testsuites>
3+
<testsuite name="Default">
4+
<directory>tests</directory>
5+
</testsuite>
6+
</testsuites>
7+
</phpunit>

0 commit comments

Comments
 (0)