Skip to content

Commit 2245d83

Browse files
freearheyfreearhey
committed
Merge branch 'dev'
2 parents 0e25bae + ebef3ae commit 2245d83

16 files changed

Lines changed: 637 additions & 497 deletions

‎.gitignore‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
vendor
22
composer.lock
33
/helpers.php
4-
/index.php
4+
/examples
55
.idea

‎.travis.yml‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,5 @@
11
language: php
22
php:
3-
- '7.0'
43
- '7.1'
54
before_script:
65
- composer install

‎README.md‎

Lines changed: 123 additions & 61 deletions
Original file line numberDiff line numberDiff line change
@@ -1,109 +1,171 @@
1-
Wikidata [![Build Status](https://travis-ci.org/freearhey/wikidata.svg?branch=master)](https://travis-ci.org/freearhey/wikidata)
2-
========
1+
[![wikidata](https://raw.githubusercontent.com/maxlath/wikidata-cli/master/assets/wikidata_logo_alone.jpg)](https://wikidata.org)
2+
3+
4+
# Wikidata [![Build Status](https://travis-ci.org/freearhey/wikidata.svg?branch=master)](https://travis-ci.org/freearhey/wikidata)
35

46
Wikidata provides a API for searching and retrieving data from [wikidata.org](https://www.wikidata.org).
57

6-
### Installation
8+
## Installation
9+
710
```sh
811
composer require freearhey/wikidata
912
```
1013

11-
### Usage
14+
## Usage
15+
16+
First we need to create an instance of `Wikidata` class and save it to some variable, like this:
1217

1318
```php
1419
$wikidata = new Wikidata();
1520
```
1621

17-
#### Search
22+
After that we can use one of the available methods to access the Wikidata database:
1823

19-
Search by entity label:
2024
```php
21-
$results = $wikidata->search('London');
25+
$wikidata->search('London');
2226
```
2327

24-
Search by Wikidata property ID and string value:
25-
```php
26-
$results = $wikidata->searchBy('P238', 'LON');
27-
```
28+
## Available Methods
2829

29-
Search by Wikidata property ID and entity ID:
30-
```php
31-
$results = $wikidata->searchBy('P17', 'Q146');
32-
```
30+
### `search()`
31+
32+
The `search()` method give you a way to find Wikidata entity by it label.
3333

34-
Check if no search results
3534
```php
36-
if($results->isEmpty()) {
37-
echo 'no results';
38-
die();
39-
}
35+
$results = $wikidata->search($query, $lang, $limit);
4036
```
4137

42-
#### Result
38+
Arguments:
4339

44-
Retrieve first result data
45-
```php
46-
$singleResult = $results->first();
47-
```
40+
- `$query`: term to search (required)
41+
- `$lang`: specify the results language (default: 'en')
42+
- `$limit`: set a custom limit (default: 10)
4843

49-
Get result ID
50-
```php
51-
$resultId = $singleResult->id; // Q84
52-
```
44+
Example:
5345

54-
Get result label
5546
```php
56-
$resultLabel = $singleResult->label; // London
47+
$results = $wikidata->search('car', 'fr', 5);
5748
```
5849

59-
Get result aliases
60-
```php
61-
$resultAliases = $singleResult->aliases; // [ 'London, UK', 'London, United Kingdom', 'London, England' ]
62-
```
50+
The `search()` method always returns `Illuminate\Support\Collection` class with results. This means you can use all the [methods available](https://laravel.com/docs/5.6/collections#available-methods) in Laravel's Collections.
6351

64-
Get result description
65-
```php
66-
$resultDescription = $singleResult->description; // capital of England and the United Kingdom
67-
```
52+
### `searchBy()`
6853

69-
#### Entity
54+
The `searchBy` help you to find Wikidata entities by it properties value.
7055

71-
Get single entity by ID:
7256
```php
73-
$entity = $wikidata->get('Q26');
57+
$results = $wikidata->searchBy($propId, $entityId, $lang, $limit);
7458
```
7559

76-
Get entity ID
77-
```php
78-
$entityId = $entity->id; // Q26
79-
```
60+
Arguments:
8061

81-
Get entity label
82-
```php
83-
$entityLabel = $entity->label; // Northern Ireland
84-
```
62+
- `$propId`: id of the property by which to search (required)
63+
- `$entityId`: id of the entity (required)
64+
- `$lang`: specify the results language (default: 'en')
65+
- `$limit`: set a custom limit (default: 10)
8566

86-
Get entity aliases
87-
```php
88-
$entityAliases = $entity->aliases; // [ 'NIR', 'UKN', 'North Ireland' ]
89-
```
67+
Example:
9068

91-
Get entity description
9269
```php
93-
$entityDescription = $entity->description; // region in north-west Europe, part of the United Kingdom
70+
// List of people who born in city Pomona, US
71+
$results = $wikidata->searchBy('P19', 'Q486868');
72+
73+
/*
74+
Collection {
75+
#items: array:10 [
76+
0 => SearchResult {
77+
id: "Q22254338"
78+
lang: "en"
79+
label: "Coco Velvett"
80+
description: "American pornographic actress"
81+
aliases: array:2 []
82+
}
83+
1 => SearchResult {
84+
id: "Q24176246"
85+
lang: "en"
86+
label: "Donald D. Engen"
87+
description: null
88+
aliases: []
89+
}
90+
...
91+
]
92+
}
93+
*/
9494
```
9595

96-
Get list of all available properties for specific entity
96+
The `searchBy()` method always returns `Illuminate\Support\Collection` class with results. This means you can use all the [methods available](https://laravel.com/docs/5.6/collections#available-methods) in Laravel's Collections.
97+
98+
### `get()`
99+
100+
The `get()` returns Wikidata entity by specified ID.
101+
97102
```php
98-
$properties = $entity->properties; // array(1) { [0]=> string(11) "instance_of", ... }
103+
$entity = $wikidata->get($entityId, $lang);
99104
```
100105

101-
Get value specific property
106+
Arguments:
107+
108+
- `$entityId`: id of the entity (required)
109+
- `$lang`: specify the results language (default: 'en')
110+
111+
Example:
112+
102113
```php
103-
$official_language = $entity->get('official_language'); // array(1) { [0]=> string(7) "English" }
114+
// Get all data about Steve Jobs
115+
$entity = $wikidata->get('Q19837');
116+
117+
/*
118+
Entity {
119+
id: "Q19837"
120+
lang: "en"
121+
label: "Steve Jobs"
122+
aliases: array:2 [
123+
0 => "Steven Jobs"
124+
1 => "Steven Paul Jobs"
125+
]
126+
description: "American entrepreneur and co-founder of Apple Inc."
127+
properties: Collection {
128+
#items: array:98 [
129+
"P18" => Property {
130+
id: "P18"
131+
label: "image"
132+
value: "http://commons.wikimedia.org/wiki/Special:FilePath/Steve%20Jobs%20Headshot%202010-CROP2.jpg"
133+
}
134+
...
135+
]
136+
}
137+
}
138+
*/
139+
140+
141+
// List of all properties as array
142+
$properties = $entity->properties->toArray();
143+
144+
/*
145+
[
146+
"P18" => Property {
147+
id: "P18"
148+
label: "image"
149+
value: "http://commons.wikimedia.org/wiki/Special:FilePath/Steve%20Jobs%20Headshot%202010-CROP2.jpg"
150+
},
151+
"P19" => Property {
152+
id: "P19"
153+
label: "place of birth"
154+
value: "San Francisco"
155+
},
156+
...
157+
]
158+
*/
159+
```
160+
161+
### Testing
162+
163+
```sh
164+
vendor/bin/phpunit
104165
```
105166

106-
That's all.
167+
### Contribution
168+
If you find a bug or want to contribute to the code or documentation, you can help by submitting an [issue](https://github.com/freearhey/wikidata/issues) or a [pull request](https://github.com/freearhey/wikidata/pulls).
107169

108170
### License
109171
Wikidata is licensed under the [MIT license](http://opensource.org/licenses/MIT).

‎composer.json‎

Lines changed: 7 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@
44
"keywords": ["wikidata", "client", "php"],
55
"homepage": "https://github.com/freearhey/wikidata",
66
"license": "MIT",
7-
"version": "2.1.1",
7+
"version": "3.0.0",
88
"authors": [
99
{
1010
"name": "Aleksandr Statciuk",
@@ -13,21 +13,22 @@
1313
}
1414
],
1515
"require": {
16-
"freearhey/sparql": "^0.0.1",
17-
"tightenco/collect": "^5.4",
16+
"tightenco/collect": "5.6.35",
1817
"guzzlehttp/guzzle": "^6.3"
1918
},
2019
"autoload": {
2120
"psr-4": {
2221
"Wikidata\\": "src"
23-
}
22+
},
23+
"files": ["src/helpers.php"]
2424
},
2525
"autoload-dev": {
2626
"psr-4": {
2727
"Tests\\": "tests"
28-
}
28+
},
29+
"files": ["src/helpers.php"]
2930
},
3031
"require-dev": {
31-
"phpunit/phpunit": "^6.4"
32+
"phpunit/phpunit": "^6.5"
3233
}
3334
}

‎phpunit.xml‎

Lines changed: 0 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -9,10 +9,6 @@
99
processIsolation="false"
1010
stopOnFailure="false">
1111
<testsuites>
12-
<testsuite name="Feature">
13-
<directory suffix="Test.php">./tests/Feature</directory>
14-
</testsuite>
15-
1612
<testsuite name="Unit">
1713
<directory suffix="Test.php">./tests/Unit</directory>
1814
</testsuite>

0 commit comments

Comments
 (0)