Skip to content

Commit bff92a6

Browse files
committed
merge
2 parents 06659b1 + 5634c56 commit bff92a6

34 files changed

+206
-144
lines changed

.gitignore

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,12 @@
1+
<<<<<<< HEAD
12
/vendor/
23
/build/
34
/doc/doc-en/
45
/doc/entities/generated.ent
6+
=======
7+
/generator/vendor/
8+
/generator/build/
9+
/generator/doc/doc-en/
10+
/generator/doc/entities/generated.ent
11+
/composer.lock
12+
>>>>>>> 5634c5679eb5adb411728e33b8d7e534faa29a19

.travis.yml

Lines changed: 15 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -8,31 +8,33 @@ matrix:
88

99
cache:
1010
directories:
11-
- doc/doc-en
11+
- generator/doc/doc-en
1212
- vendor
13+
- generator/vendor
1314
- $HOME/.composer
1415

1516
before_script:
16-
- composer install --no-interaction
17-
- mkdir -p build/logs
17+
- cd generator && composer install --no-interaction && cd ..
1818
- |
19-
if [ ! -d "doc/doc-en/en" ]; then
20-
cd doc
21-
svn co https://svn.php.net/repository/phpdoc/modules/doc-en doc-en --quiet
22-
cd ..
19+
if [ ! -d "generator/doc/doc-en/en" ]; then
20+
cd generator/doc
21+
svn co https://svn.php.net/repository/phpdoc/modules/doc-en doc-en
22+
cd ../..
2323
else
24-
cd doc/doc-en
24+
cd generator/doc/doc-en
2525
svn update
26-
cd ../..
26+
cd ../../..
2727
fi
28+
- composer update
2829

2930
script:
30-
- "./vendor/bin/phpunit"
31-
#- "./vendor/bin/composer-require-checker --config-file=composer-require-checker.json"
31+
- cd generator && ./vendor/bin/phpunit && cd ..
32+
- cd generator && composer cs-check && cd ..
33+
- cd generator && composer phpstan && cd ..
3234
- composer cs-check
3335
- composer phpstan
3436
# Now, let's regenerate all files and see if we obtain the same set of files as the ones commited:
35-
- ./safe.php generate
37+
- cd generator && ./safe.php generate && cd ..
3638
- |
3739
if output=$(git status --porcelain) && [ -z "$output" ]; then
3840
# all is good
@@ -42,5 +44,6 @@ script:
4244
echo "Generated files are different from commited files. Please run './safe.php generate' command and commit the results."
4345
exit 1;
4446
fi
47+
4548
after_script:
4649
- travis_retry php vendor/bin/php-coveralls

CONTRIBUTING.md

Lines changed: 11 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -7,31 +7,25 @@ Safe-PHP code is generated automatically from the PHP doc.
77
The first step is to download the PHP documentation project locally.
88
You will need Subversion (svn) installed on your computer.
99

10+
```bash
11+
$ cd generator/doc
12+
$ svn co https://svn.php.net/repository/phpdoc/modules/doc-en doc-en
13+
$ cd ../..
1014
```
11-
cd doc
12-
svn co https://svn.php.net/repository/phpdoc/modules/doc-en doc-en
13-
cd ..
14-
```
15-
16-
Generating the documentation is a 2 pass process.
1715

18-
### First pass: generating the function list
16+
At any point, if you want to update the documentation to the latest version, you can use:
1917

2018
```bash
21-
php ./parse.php
19+
$ cd generator/doc/doc-en
20+
$ svn update
2221
```
2322

24-
The first pass is used to find all the functions in the documentation and to put them in a CSV file called `generated/functions.csv`
2523

26-
This CSV file is then **manually edited** to cope for the specific cases of some functions (for instance, the cURL exception
27-
messages can be fetched from `curl_strerror`).
24+
### Generating the functions
2825

29-
### Second pass: generating the function list
26+
Generating the functions can be done with a simple command line.
3027

3128
```bash
32-
php ./generate.php
29+
$ cd generator
30+
$ php ./safe.php generate
3331
```
34-
35-
The second pass uses the `generated/functions.csv` and the downloaded documentation to create the functions wrapper file
36-
in `generated/lib.php`.
37-

README.md

Lines changed: 36 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -51,14 +51,34 @@ throwing exceptions properly when an error is encountered. The "safe" functions
5151
functions, except they are in the `Safe` namespace.
5252

5353
```php
54-
use Safe\file_get_contents;
55-
use Safe\json_decode;
54+
use function Safe\file_get_contents;
55+
use function Safe\json_decode;
5656

5757
// This code is both safe and simple!
5858
$content = file_get_contents('foobar.json');
5959
$foobar = json_decode($content);
6060
```
6161

62+
## PHPStan integration
63+
64+
> Yeah... but I must explicitly think about importing the "safe" variant of the function, for each and every file of my application.
65+
> I'm sure I will forget some "use function" statements!
66+
67+
Fear not! thecodingmachine/safe comes with a PHPStan rule.
68+
69+
Never heard of [PHPStan](https://github.com/phpstan/phpstan) before?
70+
Check it out, it's an amazing code analyzer for PHP.
71+
72+
Simply install the Safe rule in your PHPStan setup and PHPStan will let you know each time you are using an "unsafe" function:
73+
74+
The code below will trigger this warning:
75+
76+
```php
77+
$content = file_get_contents('foobar.json');
78+
```
79+
80+
> Function file_get_contents is unsafe to use. It can return FALSE instead of throwing an exception. Please add 'use function Safe\\file_get_contents;' at the beginning of the file to use the variant provided by the 'thecodingmachine/safe' library.
81+
6282
## Installation
6383

6484
Use composer to install Safe-PHP:
@@ -67,16 +87,25 @@ Use composer to install Safe-PHP:
6787
$ composer require thecodingmachine/safe
6888
```
6989

90+
*Highly recommended*: install PHPStan and PHPStan extension:
7091

92+
```bash
93+
$ composer require --dev thecodingmachine/phpstan-safe-rule
94+
```
95+
96+
Now, edit your `phpstan.neon` file and add these rules:
7197

72-
## TODO:
98+
```yml
99+
includes:
100+
- vendor/thecodingmachine/phpstan-safe-rule/phpstan-safe-rule.neon
101+
```
73102
74-
- handle objects methods overloading
75-
- develop a PHPStan extension
76103
104+
## Work in progress
77105
106+
There are a number of issues withstanding [before releasing 1.0](https://github.com/thecodingmachine/safe/milestone/1)
78107
79108
## Contributing
80109
81-
The `lib.php` file that contains all the functions is auto-generated from the PHP doc.
82-
Read the [CONTRIBUTING.md](CONTRIBUTING.md) file to learn how to regenerate it and to contribute to this library.
110+
The files that contains all the functions are auto-generated from the PHP doc.
111+
Read the [CONTRIBUTING.md](CONTRIBUTING.md) file to learn how to regenerate these files and to contribute to this library.

composer.json

Lines changed: 9 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -1,33 +1,25 @@
11
{
22
"name": "thecodingmachine/safe",
3-
"description": "Create a list of functional PHP functions which return false on error",
3+
"description": "PHP core functions that throw exceptions instead of returning FALSE on error",
44
"autoload": {
55
"psr-4": {
66
"Safe\\": ["lib/", "generated/"]
77
}
88
},
9-
"autoload-dev": {
10-
"psr-4": {
11-
"Safe\\": "src/"
12-
}
13-
},
149
"require-dev": {
1510
"php": ">=7.1",
16-
"ext-simplexml": "*",
17-
"phpunit/phpunit": "^7",
18-
"phpstan/phpstan": "^0.10.2",
19-
"thecodingmachine/phpstan-strict-rules": "^0.10",
20-
"phpoffice/phpspreadsheet": "^1.4",
21-
"ext-json": "^1.5",
22-
"symfony/console": "^4.1.4",
23-
"squizlabs/php_codesniffer": "^3.2",
24-
"php-coveralls/php-coveralls": "^2.1"
11+
"phpstan/phpstan": "^0.10.3",
12+
"thecodingmachine/phpstan-strict-rules": "^0.10.3",
13+
"squizlabs/php_codesniffer": "^3.2"
2514
},
2615
"scripts": {
27-
"phpstan": "phpstan analyse src -c phpstan.neon --level=7 --no-progress -vvv",
16+
"phpstan": "phpstan analyse lib -c phpstan.neon --level=7 --no-progress -vvv",
2817
"cs-fix": "phpcbf",
2918
"cs-check": "phpcs"
3019
},
31-
"require": {
20+
"extra": {
21+
"branch-alias": {
22+
"dev-master": "0.1-dev"
23+
}
3224
}
3325
}

doc/entities/.gitkeep

Whitespace-only changes.

generator/composer.json

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
{
2+
"name": "thecodingmachine/safe-generator",
3+
"description": "Generated the files for thecodingmachine/safe",
4+
"autoload-dev": {
5+
"psr-4": {
6+
"Safe\\": "src/"
7+
}
8+
},
9+
"require-dev": {
10+
"php": ">=7.1",
11+
"ext-simplexml": "*",
12+
"phpunit/phpunit": "^7",
13+
"phpstan/phpstan": "^0.10.3",
14+
"thecodingmachine/phpstan-strict-rules": "^0.10.3",
15+
"phpoffice/phpspreadsheet": "^1.4",
16+
"ext-json": "^1.5",
17+
"symfony/console": "^4.1.4",
18+
"squizlabs/php_codesniffer": "^3.2",
19+
"php-coveralls/php-coveralls": "^2.1"
20+
},
21+
"scripts": {
22+
"phpstan": "phpstan analyse src -c phpstan.neon --level=7 --no-progress -vvv",
23+
"cs-fix": "phpcbf",
24+
"cs-check": "phpcs"
25+
},
26+
"extra": {
27+
"branch-alias": {
28+
"dev-master": "0.1-dev"
29+
}
30+
}
31+
}

composer.lock renamed to generator/composer.lock

Lines changed: 1 addition & 1 deletion
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.
File renamed without changes.

generator/phpcs.xml.dist

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
<?xml version="1.0"?>
2+
<ruleset name="Expressive Skeleton coding standard">
3+
<description>Expressive Skeleton coding standard</description>
4+
5+
<!-- display progress -->
6+
<arg value="p"/>
7+
<arg name="colors"/>
8+
9+
<!-- inherit rules from: -->
10+
<rule ref="PSR2"/>
11+
12+
<!-- Paths to check -->
13+
<file>src</file>
14+
15+
<rule ref="Generic.Files.LineLength">
16+
<properties>
17+
<property name="lineLimit" value="300"/>
18+
<property name="absoluteLineLimit" value="500"/>
19+
</properties>
20+
</rule>
21+
</ruleset>

0 commit comments

Comments
 (0)