Skip to content

Commit 23b7161

Browse files
ondrejmirtesondrejmirtes
committed
Website - Discovering Symbols
1 parent bc3205f commit 23b7161

9 files changed

Lines changed: 131 additions & 13 deletions

File tree

‎website/src/_layouts/_user_guide.njk‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,7 @@ sectionTitle: User Guide
77
{% extends "./_sidebar.njk" %}
88

99
{% block banner %}
10+
{% if showBanner %}
1011
<div class="bg-green-100 border-2 rounded-lg border-green-500 text-green-700 p-4 mt-4 mb-4" role="alert">
1112

1213
<p>Interested in mastering your PHP craft and getting the most out of PHPStan? Ondřej&nbsp;Mirtes (the creator of PHPStan) will hold a <strong>3-hour interactive workshop</strong> as part of the online Dutch PHP Conference on <strong>June 25th 2020</strong>.</p>
@@ -16,6 +17,7 @@ sectionTitle: User Guide
1617
<a target="_blank" class="font-bold" href="https://ibuildings.paydro.com/dutch-php-conference-2020">Buy a ticket and secure your place! »</a>
1718

1819
</div>
20+
{% endif %}
1921
{% endblock %}
2022

2123
{% block scripts %}

‎website/src/config-reference.md‎

Lines changed: 13 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -83,6 +83,13 @@ Learn more about ignoring errors in the [user guide](/user-guide/ignoring-errors
8383

8484
Related config keys: `ignoreErrors`, `reportUnmatchedIgnoredErrors`.
8585

86+
Discovering symbols
87+
------------------
88+
89+
Learn more about discovering symbols in the [user guide](/user-guide/discovering-symbols).
90+
91+
Related config keys: `scanFiles`, `scanDirectories`.
92+
8693
Autoloading
8794
------------------
8895

@@ -93,14 +100,15 @@ Related config keys: `autoload_directories`, `autoload_files`.
93100
Bootstrap
94101
------------------
95102

96-
If you need to initialize something in PHP runtime before PHPStan runs (like your own autoloader), you can provide your own bootstrap file:
103+
If you need to initialize something in PHP runtime before PHPStan runs (like your own autoloader), you can provide your own bootstrap files:
97104

98105
```yaml
99106
parameters:
100-
bootstrap: phpstan-bootstrap.php
107+
bootstrapFiles:
108+
- phpstan-bootstrap.php
101109
```
102110

103-
Relative path in the `bootstrap` key is resolved based on the directory of the config file is in.
111+
Relative paths in the `bootstrapFiles` key are resolved based on the directory of the config file is in.
104112

105113
Caching
106114
------------------
@@ -141,7 +149,7 @@ If you provide analysed paths to PHPStan on the command line and in the config f
141149

142150
You should only analyse files with the code you've written yourself. There's no need to analyse the `vendor` directory with 3rd party dependencies because it's not in your power to fix all the mistakes made by the developers you don't work with directly.
143151

144-
Yes, PHPStan needs to know about all the classes, interfaces, traits, and functions your code uses, but that's achieved through [autoloading](/user-guide/autoloading), not by including the files in the analysis.
152+
Yes, PHPStan needs to know about all the classes, interfaces, traits, and functions your code uses, but that's achieved through [discovering symbols](/user-guide/discovering-symbols), not by including the files in the analysis.
145153

146154
</div>
147155

@@ -214,7 +222,7 @@ parameters:
214222
Constants
215223
---------------
216224

217-
Learn more about letting PHPStan know about your global constants in [the user guide](/user-guide/autoloading).
225+
Learn more about letting PHPStan know about your global constants in [the user guide](/user-guide/discovering-symbols).
218226

219227
Sometimes your constants can have different values in different environments, like `DATABASE_ENGINE` that can have different values like `mysql` or `pgsql`. To let PHPStan know that the value of the constant can be different, and prevent errors like `Strict comparison using === between 'pgsql' and 'mysql' will always evaluate to false.`, add the constant name to `dynamicConstantNames` key:
220228

‎website/src/user-guide/autoloading.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,14 @@
11
---
22
title: Autoloading
3+
showBanner: false
34
---
45

6+
<div class="bg-yellow-100 border-l-4 border-yellow-500 text-yellow-700 p-4 mb-4" role="alert">
7+
8+
Autoloading has been deprecated in favor of [Discovering Symbols](/user-guide/discovering-symbols) in PHPStan 0.12.26. Make sure to upgrade to the latest version and take advantage of the latest features!
9+
10+
</div>
11+
512
PHPStan needs a working autoloader to access reflection of the analysed classes. It uses Composer autoloader in the project by looking at `vendor/autoload.php` from the current working directory. Use the `autoload`/`autoload-dev` sections in `composer.json` to configure the autoloader.
613

714
If PHPStan complains about some non-existent classes [^class-not-found] and you're sure the classes exist in the codebase and you don't want to use Composer autoloader, you can specify directories to scan and concrete files to include using `autoload_directories` and `autoload_files` parameters in the [configuration file](/config-reference).

‎website/src/user-guide/command-line-usage.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -35,7 +35,7 @@ Please note that the exit code differs in this case. Exit code 0 means that the
3535

3636
If your application uses a custom autoloader, you should set it up and register in a PHP file that is passed to this CLI option. Relative paths are resolved based on the current working directory.
3737

38-
[Learn more about autoloading »](/user-guide/autoloading)
38+
[Learn more »](/user-guide/discovering-symbols)
3939

4040
### `--error-format`
4141

@@ -101,7 +101,7 @@ Specifies the path to a [configuration file](/config-reference). Relative paths
101101

102102
If your application uses a custom autoloader, you should set it up and register in a PHP file that is passed to this CLI option. Relative paths are resolved based on the current working directory.
103103

104-
[Learn more about autoloading »](/user-guide/autoloading)
104+
[Learn more »](/user-guide/discovering-symbols)
105105

106106
### `--quiet|-q`
107107

‎website/src/user-guide/discovering-symbols.md‎

Lines changed: 100 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,100 @@
1+
---
2+
title: Discovering Symbols
3+
showBanner: false
4+
---
5+
6+
<div class="bg-green-100 border-l-4 border-green-500 text-green-700 p-4 mb-4" role="alert">
7+
8+
Discovering Symbols is a new feature in PHPStan 0.12.26. Make sure to upgrade to the latest version and take advantage of the latest features!
9+
10+
Looking for the deprecated [autoloading](/user-guide/autoloading) instead?
11+
12+
</div>
13+
14+
PHPStan needs to be able to locate symbols (classes, functions, constants) used in the analysed codebase. By default, it looks for them in these two places:
15+
16+
* Analysed paths (files and directories) passed as [command line arguments](/user-guide/command-line-usage) and in the [configuration file](/config-reference#analysed-files).
17+
* Composer dependencies of the analysed project
18+
19+
This covers most common needs.
20+
21+
However, there are some advanced scenarios that might require some additional configuration.
22+
23+
Third party code outside of Composer dependencies
24+
---------------------------
25+
26+
If your project uses some code that isn't part of your Composer dependencies, but you don't wish to analyse it, you can take advantage of `scanFiles` and `scanDirectories` config options:
27+
28+
```yaml
29+
parameters:
30+
scanFiles:
31+
- Foo.class.php
32+
scanDirectories:
33+
- classes
34+
```
35+
36+
Relative paths in the `scanFiles` and `scanDirectories` keys are resolved based on the directory of the config file is in.
37+
38+
Global constants
39+
---------------------------
40+
41+
Global constants used in the analysed code need to be defined in bootstrap files.
42+
43+
Create a file a that looks like this:
44+
45+
```php
46+
<?php
47+
48+
define('MY_CONSTANT', 1);
49+
```
50+
51+
And add it to your [configuration file](/config-reference):
52+
53+
```yaml
54+
parameters:
55+
bootstrapFiles:
56+
- constants.php
57+
```
58+
59+
Please note that bootstrap files will actually be executed by the PHP runtime.
60+
61+
Class aliases
62+
---------------------------
63+
64+
This is similar to global constants above. Class aliases used in the analysed code need to be defined in bootstrap files.
65+
66+
Create a file a that looks like this:
67+
68+
```php
69+
<?php
70+
71+
class_alias(\Foo::class, 'Bar');
72+
```
73+
74+
And add it to your [configuration file](/config-reference):
75+
76+
```yaml
77+
parameters:
78+
bootstrapFiles:
79+
- classAliases.php
80+
```
81+
82+
Please note that bootstrap files will actually be executed by the PHP runtime.
83+
84+
Custom autoloader
85+
---------------------------
86+
87+
If you're using some other autoloader than the one in Composer, PHPStan can take advantage of it to discover files with autoloaded classes.
88+
89+
You can register the custom autoloader in two ways:
90+
91+
1) By passing the PHP file that registers the autoloader as [`--autoload-file|-a` on the command line](/user-guide/command-line-usage#--autoload-file|-a).
92+
2) By using the `bootstrapFiles` option:
93+
94+
```yaml
95+
parameters:
96+
bootstrapFiles:
97+
- my_autoloader.php
98+
```
99+
100+
Please note that the file with the autoloader will actually be executed by the PHP runtime.

‎website/src/user-guide/getting-started.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -38,7 +38,7 @@ vendor/bin/phpstan analyse src tests
3838

3939
You should only analyse files with the code you've written yourself. There's no need to analyse the `vendor` directory with 3rd party dependencies because it's not in your power to fix all the mistakes made by the developers you don't work with directly.
4040

41-
Yes, PHPStan needs to know about all the classes, interfaces, traits, and functions your code uses, but that's achieved through [autoloading](/user-guide/autoloading), not by including the files in the analysis.
41+
Yes, PHPStan needs to know about all the classes, interfaces, traits, and functions your code uses, but that's achieved through [discovering symbols](/user-guide/discovering-symbols), not by including the files in the analysis.
4242
</div>
4343

4444
[Learn more about command line options »](/user-guide/command-line-usage)
@@ -48,7 +48,7 @@ PHPStan will probably find some errors, but don't worry, your code might be just
4848
* Extra arguments passed to functions (e. g. function requires two arguments, the code passes three)
4949
* Extra arguments passed to print/sprintf functions (e. g. format string contains one placeholder, the code passes two values to replace)
5050
* Obvious errors in dead code
51-
* Autoloading issues - "class not found" even if it exists. See [Autoloading](/user-guide/autoloading) for more details.
51+
* Unknown symbols - like "class not found". See [Discovering Symbols](/user-guide/discovering-symbols) for more details.
5252

5353
**By default, PHPStan runs only the most basic checks. Head to [Rule Levels](/user-guide/rule-levels) to learn how to turn on stricter checks.**
5454

‎website/src/user-guide/result-cache.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ PHPStan caches the result of the analysis so the subsequent runs are much faster
66

77
<div class="bg-blue-100 border-l-4 border-blue-500 text-blue-700 p-4 mb-4" role="alert">
88

9-
You might notice the result cache isn't sometimes saved and PHPStan runs full analysis even if nothing changed since the last run. If the analysis result contains some serious errors like parse errors or [autoloading errors](/user-guide/autoloading), result cache cannot be used for the next run because the files dependency tree might be incomplete.
9+
You might notice the result cache isn't sometimes saved and PHPStan runs full analysis even if nothing changed since the last run. If the analysis result contains some serious errors like parse errors, result cache cannot be used for the next run because the files dependency tree might be incomplete.
1010

1111
</div>
1212

‎website/src/user-guide/stub-files.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ PHPStan depends on [PHPDocs](/writing-php-code/phpdocs-basics) in the analysed a
66

77
To mitigate this, you can write a stub file with the right PHPDoc. It's like source code, but PHPStan only reads PHPDocs from it. So the namespace and class/interface/trait/method/function names must match with the original source you're describing. But method bodies can stay empty, PHPStan is only interested in the PHPDocs. Get inspired by [the stubs PHPStan itself uses](https://github.com/phpstan/phpstan-src/tree/master/stubs) or by [the stubs from the phpstan-doctrine extension](https://github.com/phpstan/phpstan-doctrine/tree/master/stubs).
88

9-
Stub files aren't a replacement for [autoloading](/user-guide/autoloading) so if you're trying to fix errors like "Function not found" or "Class not found", check out the [autoloading](/user-guide/autoloading) guide instead.
9+
Stub files aren't a replacement for [discovering symbols](/user-guide/discovering-symbols) so if you're trying to fix errors like "Function not found" or "Class not found", check out the [discovering symbols](/user-guide/discovering-symbols) guide instead.
1010

1111
<div class="bg-blue-100 border-l-4 border-blue-500 text-blue-700 p-4 mb-4" role="alert">
1212

‎website/src/user-guide/user-guide.json‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
{
22
"layout": "_user_guide.njk",
3+
"showBanner": true,
34
"sidebarOtherSections": [
45
{
56
"title": "Config Reference",
@@ -32,8 +33,8 @@
3233
"link": "/user-guide/baseline"
3334
},
3435
{
35-
"title": "Autoloading",
36-
"link": "/user-guide/autoloading"
36+
"title": "Discovering Symbols",
37+
"link": "/user-guide/discovering-symbols"
3738
},
3839
{
3940
"title": "Output Format",

0 commit comments

Comments
 (0)