Skip to content

Commit b9a4360

Browse files
forocoforoco
committed
Version 1.0 (release)
1 parent 47057af commit b9a4360

File tree

9 files changed

+1862
-2
lines changed

9 files changed

+1862
-2
lines changed

‎README.md

Lines changed: 356 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,356 @@
1-
# php-browser-detection
2-
Ultra fast PHP library to detect browser, OS, platform and device type by User-Agent parsing
1+
# PHP Browser Detection
2+
3+
A PHP library to detect browser, OS, platform and device type by User-Agent parsing.\
4+
This library focused on high performance and low memory usage HTTP client parsing.\
5+
Uses a simple and fast algorithm to accurate detection more than 100 browsers types and ~ 58 OS types.\
6+
For most commonly browsers parsing process tooks less than 0.0005 second even on low-level shared hosting.\
7+
In the case of very unusual User-Agents recognized time is less than 0.0008 second for same conditioned hosting environment.\
8+
The library supports only really actual Browsers and OS without support for outdated environments that are actually not used now.\
9+
Works by use only one library file and without any third-party libraries dependency.
10+
11+
## Requirements
12+
13+
This library requires PHP 5.3 or higher.
14+
15+
## Installation
16+
17+
To install, you can use composer:
18+
19+
`
20+
composer require foroco/php-browser-detection
21+
`
22+
23+
Or simply upload library file `BrowserDetection.php` (placed in the `src` directory) to your project and connect it in PHP script by use `require_once` (see usage cases bellow).
24+
25+
## Usage
26+
27+
The library will try to get environment data from the `HTTP_USER_AGENT` header sent by the HTTP client.
28+
Library PHP Class `BrowserDetection` contains four public methods which returns Array or JSON string of recognized data from `HTTP_USER_AGENT`:
29+
30+
* `getAll();`
31+
* `getOS();`
32+
* `getBrowser();`
33+
* `getDevice();`
34+
35+
First argument should contains User-Agent string from the `HTTP_USER_AGENT` header or your custom User-Agent string.\
36+
Second argument (optional) may contains 'JSON' if you want to get returned result as JSON format.
37+
38+
```php
39+
<?php
40+
require_once('BrowserDetection.php');
41+
$Browser = new BrowserDetection();
42+
43+
$useragent = $_SERVER['HTTP_USER_AGENT'];
44+
45+
// Get all possible environment data (array):
46+
$result = $Browser->getAll($useragent);
47+
48+
// Get OS data (array):
49+
$result = $Browser->getOS($useragent);
50+
51+
// Get Browser data (array):
52+
$result = $Browser->getBrowser($useragent);
53+
54+
// Get Device type data (array):
55+
$result = $Browser->getDevice($useragent);
56+
57+
/*
58+
Also methods may returned result as JSON string
59+
Just use second argument of methods as 'JSON'
60+
*/
61+
62+
// Get all possible environment data (JSON):
63+
$result = $Browser->getAll($useragent, 'JSON');
64+
65+
// ... etc
66+
?>
67+
```
68+
69+
## Description for returned variables
70+
71+
**OS Type** (`os_type`)\
72+
Returns type of operating system (OS).\
73+
All possible values:
74+
* desktop
75+
* mobile
76+
* mixed
77+
* unknown
78+
79+
**OS Family** (`os_family`)\
80+
Returns operating system (OS) family or `unknown` in cases of unable OS family recognition.\
81+
Example: `windows`, `linux`, `unix` etc.
82+
83+
**OS Name** (`os_name`)\
84+
Returns operating system (OS) name or `unknown` in cases of unable OS name recognition.\
85+
Example: `Windows`, `Android`, `macOS`, `iOS` etc.
86+
87+
**OS Version** (`os_version`)\
88+
Returns operating system (OS) version or `0` in cases of unable OS version recognition.\
89+
May contains numeric, string or mixed types OS versions.\
90+
In case of numeric OS version (e.g. `Android`) contains major and minor version parts values, e.g. `4.4`, `8.1`, `10` etc.\
91+
In case of string OS version (e.g. `macOS`) contains string version name values, e.g. `Mavericks`, `Mojave`, `Catalina` etc.\
92+
For `Windows` may contains mixed version types values: `10`, `Vista`, `XP` etc.
93+
94+
**OS Title** (`os_title`)\
95+
Returns operating system (OS) title which contains OS name and OS version together.\
96+
Also returns `unknown` if OS name is not recognized.
97+
98+
**Device Type** (`device_type`)\
99+
Returns device type based on some User-Agent data.\
100+
All possible values:
101+
* desktop
102+
* mobile
103+
* tv
104+
* console
105+
* mediaplayer
106+
* car
107+
* watch
108+
* unknown
109+
110+
**Browser Name** (`browser_name`)\
111+
Returns browser name or `unknown` in cases of unable browser name recognition.\
112+
Example: `Chrome`, `Firefox`, `UC Browser`, `Huawei Browser`, `Vivaldi` etc.
113+
114+
**Browser Version** (`browser_version`)\
115+
Returns browser version number or `0` in cases of unable browser version recognition.\
116+
Always contains numeric values (integer or float numbers).\
117+
Returns float number (e.g. `3.5`, `10.5`, `13.1`) for some browsers which should contains both major and minor browser version parts (`Safari`, `Vivaldi`, `PaleMoon` etc).\
118+
Returns only major decimal browser version (e.g. `15`, `37`, `81`) for other browsers which has a lot of major versions (`Chrome`, `Firefox`, `Opera` etc).
119+
120+
**Browser Title** (`browser_title`)\
121+
Returns browser title which contains browser name and browser version together.\
122+
Also returns `unknown` if browser name is not recognized.
123+
124+
**Browser Chrome Original** (`browser_chrome_original`)\
125+
Returns `1` number if browser recognized as original Google Chrome browser or returns `0` if it's not.
126+
127+
**Browser Firefox Original** (`browser_firefox_original`)\
128+
Returns `1` number if browser recognized as original Mozilla Firefox browser or returns `0` if it's not.
129+
130+
**Browser Safari Original** (`browser_safari_original`)\
131+
Returns `1` number if browser recognized as original Apple Safari browser or returns `0` if it's not.
132+
133+
**Browser Chromium Version** (`browser_chromium_version`)\
134+
Returns Chromium major engine version number if browser based on Chromium engine or returns `0` if it's not.
135+
136+
**Browser Gecko Version** (`browser_gecko_version`)\
137+
Returns Gecko major engine version number if browser based on Gecko engine or returns `0` if it's not.
138+
139+
**Browser WebKit Version** (`browser_webkit_version`)\
140+
Returns WebKit version engine number if browser based on WebKit engine or returns `0` if it's not.\
141+
Always float number value.
142+
143+
**Browser Android Webview** (`browser_android_webview`)\
144+
Returns `1` number if Android Webview mode detected or returns `0` if it's not.
145+
146+
**Browser iOS Webview** (`browser_ios_webview`)\
147+
Returns `1` number if iOS Webview mode detected or returns `0` if it's not.
148+
149+
## Usage Examples
150+
151+
See follow examples to understand library usage use cases.
152+
153+
### Detect All
154+
155+
To detect all possible environment data use:
156+
157+
```php
158+
<?php
159+
require_once('BrowserDetection.php');
160+
$Browser = new BrowserDetection();
161+
162+
$useragent = 'Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/80.0.4150.0 Iron Safari/537.36';
163+
$result = $Browser->getAll($useragent);
164+
print_r($result);
165+
?>
166+
```
167+
168+
Returns:
169+
170+
```
171+
Array
172+
(
173+
[os_type] => desktop
174+
[os_family] => windows
175+
[os_name] => Windows
176+
[os_version] => 7
177+
[os_title] => Windows 7
178+
[device_type] => desktop
179+
[browser_name] => Iron
180+
[browser_version] => 80
181+
[browser_title] => Iron 80
182+
[browser_chrome_original] => 0
183+
[browser_firefox_original] => 0
184+
[browser_safari_original] => 0
185+
[browser_chromium_version] => 80
186+
[browser_gecko_version] => 0
187+
[browser_webkit_version] => 0
188+
[browser_android_webview] => 0
189+
[browser_ios_webview] => 0
190+
)
191+
```
192+
193+
### OS Detection
194+
195+
To parse only OS data use:
196+
197+
```php
198+
<?php
199+
require_once('BrowserDetection.php');
200+
$Browser = new BrowserDetection();
201+
202+
$useragent = 'Mozilla/5.0 (Android 8.1.0; Tablet; rv:68.6.0) Gecko/68.6.0 Firefox/68.6.0';
203+
$result = $Browser->getBrowser($useragent);
204+
print_r($result);
205+
?>
206+
```
207+
208+
Returns:
209+
210+
```
211+
Array
212+
(
213+
[os_type] => mobile
214+
[os_family] => android
215+
[os_name] => Android
216+
[os_version] => 8.1
217+
[os_title] => Android 8.1
218+
)
219+
```
220+
221+
### Browser Detection
222+
223+
To parse only browser data use:
224+
225+
```php
226+
<?php
227+
require_once('BrowserDetection.php');
228+
$Browser = new BrowserDetection();
229+
230+
$useragent = 'Mozilla/5.0 (iPad; CPU OS 9_3_4 like Mac OS X) AppleWebKit/601.1 (KHTML, like Gecko) CriOS/80.0.3987.122 Mobile/13G35 Safari/601.1.46';
231+
$result = $Browser->getBrowser($useragent);
232+
print_r($result);
233+
?>
234+
```
235+
236+
Returns:
237+
238+
```
239+
Array
240+
(
241+
[browser_name] => Chrome
242+
[browser_version] => 80
243+
[browser_title] => Chrome 80
244+
[browser_chrome_original] => 1
245+
[browser_firefox_original] => 0
246+
[browser_safari_original] => 0
247+
[browser_chromium_version] => 80
248+
[browser_gecko_version] => 0
249+
[browser_webkit_version] => 0
250+
[browser_android_webview] => 0
251+
[browser_ios_webview] => 0
252+
)
253+
```
254+
255+
### Device Detection
256+
257+
To parse only device type data use:
258+
259+
```php
260+
<?php
261+
require_once('BrowserDetection.php');
262+
$Browser = new BrowserDetection();
263+
264+
$useragent = 'MEmpresas/20180706 CFNetwork/808.2.16 Darwin/17.4.0';
265+
$result = $Browser->getBrowser($useragent);
266+
print_r($result);
267+
?>
268+
```
269+
270+
Returns:
271+
272+
```
273+
Array
274+
(
275+
[device_type] => mobile
276+
)
277+
```
278+
279+
### Detect All (JSON)
280+
281+
To pasre all possible environment data and returns JSON format string:
282+
283+
```php
284+
<?php
285+
require_once('BrowserDetection.php');
286+
$Browser = new BrowserDetection();
287+
288+
$useragent = 'Mozilla/5.0 (iPhone; CPU iPhone OS 6_0 like Mac OS X) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/78.0.3904.108 Mobile Safari/537.36';
289+
$result = $Browser->getAll($useragent);
290+
print_r($result);
291+
?>
292+
```
293+
294+
Returns:
295+
296+
```
297+
{"os_type":"mobile","os_family":"macintosh","os_name":"iOS","os_version":6,"os_title":"iOS 6","device_type":"mobile","browser_name":"Chrome","browser_version":78,"browser_title":"Chrome 78","browser_chrome_original":1,"browser_firefox_original":0,"browser_safari_original":0,"browser_chromium_version":78,"browser_gecko_version":0,"browser_webkit_version":0,"browser_android_webview":0,"browser_ios_webview":0}
298+
```
299+
300+
## Benchmarking Tests
301+
302+
Benchmarking was performed on a low-level shared hosting.\
303+
Test server configuration: RedHat Linux + LiteSpeed + PHP Extension.\
304+
Test conditions based on collection of random ~446000 non repeated real life User-Agent strings.
305+
306+
Recognition performance PHP v5.3 (Requests Per Second):
307+
308+
`Benchmark PHP 5.3:`
309+
310+
```
311+
getAll: ~ 5300 rps
312+
getOS: ~ 24000 rps
313+
getBrowser: ~ 5900 rps
314+
getDevice: ~ 16000 rps
315+
```
316+
317+
`Benchmark PHP 5.6:`
318+
319+
```
320+
getAll: ~ 6300 rps
321+
getOS: ~ 31000 rps
322+
getBrowser: ~ 7600 rps
323+
getDevice: ~ 19000 rps
324+
```
325+
326+
`Benchmark PHP 7.3:`
327+
328+
```
329+
getAll: ~ 31000 rps
330+
getOS: ~ 120000 rps
331+
getBrowser: ~ 43000 rps
332+
getDevice: ~ 70000 rps
333+
```
334+
335+
## License
336+
337+
The MIT License (MIT)
338+
339+
Copyright (c) 2020 Artem Murugov
340+
341+
Permission is hereby granted, free of charge, to any person obtaining a copy of
342+
this software and associated documentation files (the "Software"), to deal in
343+
the Software without restriction, including without limitation the rights to
344+
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
345+
the Software, and to permit persons to whom the Software is furnished to do so,
346+
subject to the following conditions:
347+
348+
The above copyright notice and this permission notice shall be included in all
349+
copies or substantial portions of the Software.
350+
351+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
352+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
353+
FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
354+
COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
355+
IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
356+
CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

‎composer.json

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
{
2+
"name": "foroco/php-browser-detection",
3+
"type": "library",
4+
"description": "Ultra fast PHP library to detect browser, OS, platform and device type by User-Agent parsing.",
5+
"keywords": ["user-agent","php","browser","detection","environment","useragent"],
6+
"homepage": "https://github.com/foroco/php-browser-detection",
7+
"license": "MIT",
8+
"authors": [
9+
{
10+
"name": "Artem Murugov",
11+
"email": "[email protected]",
12+
"homepage": "https://github.com/foroco/",
13+
"role": "Developer"
14+
}
15+
],
16+
"require": {
17+
"php": ">=5.3.0"
18+
},
19+
"autoload": {
20+
"classmap": [
21+
"src/BrowserDetection.php"
22+
]
23+
}
24+
}

0 commit comments

Comments
 (0)