etsy/phan

Layout of src/Phan
==================

Also see https://github.com/phan/phan/wiki/Developer%27s-Guide-To-Phan

Folders
-------

### Analysis
Classes that analyze ASTS. They may do one or more of the following things:

- Emit issues.
- Update Phan's internal state.
- Compute inferences about a given block of code, and update Phan's state for that block (e.g. ConditionVisitor)
- See https://github.com/phan/phan/wiki/Developer%27s-Guide-To-Phan#parsing-and-analysis

### AST

Classes that work with ASTs

- Classes
- ContextNode, which gets information about an AST in it's Context
- Base classes for the different types of visitors

### Daemon

Classes used when Phan is running in the background and receiving requests ("daemon mode"). Also see `LanguageServer/`

- Classes for requests and responses the Phan-specific protocol (i.e. used by `phan_client`)
- Logic for forking off workers to analyze the `CodeBase`, then to receive the analysis results.

### Debug

Utilities for developers working on Phan to debug it.

### Exception

Exception classes used by Phan's implementation.

### Language

Contains data structures for representations of PHP code bases, and methods acting on those data structures.

- E.g. `Context`, `Element`, `FQSEN`, `Internal`, `Scope`, `Type`
- See https://github.com/phan/phan/wiki/Developer%27s-Guide-To-Phan#core-concepts

### LanguageServer

Contains an implementation of the [Language Server Protocol](https://github.com/Microsoft/language-server-protocol), which is a common protocol supported in various IDEs.
Also see `Daemon/`

- Classes that get received and sent over JSON RPC2
- Logic for forking off workers to analyze the `CodeBase`, then to receive the analysis results.

### Library

Contains reusable data structures that aren't specific to analyzing PHP. (Map, Set, Option, Tuple, Hasher, etc.)

### Output

This contains implementation details for printing out Phan issues.
This includes formatters (text, JSON, pylint, etc.) as well as how Phan would colorize issues.

### Parse

This contains implementation details for Phan's initial parse phase.
In the parse phase, all code is parsed in order to build maps from FQSENs to elements.

- See https://github.com/phan/phan/wiki/Developer%27s-Guide-To-Phan#parsing-and-analysis

### Plugin

This contains implementation details for working with the set of plugins loaded by the user (ConfigPluginSet).
`Plugin/Internal` also contains plugins Phan loads automatically (e.g. for improving analysis of `array_map`, `call_user_func`, etc.)

### PluginV3

This contains the current implementation (v3) of the plugin system.
`*Capability.php` contains capabilities that PluginV3 instances can extend.
See https://github.com/phan/phan/wiki/Writing-Plugins-for-Phan for more information on plugin development.

Files
-----

### Analysis.php

This class is the entry point into the static analyzer.

### BlockAnalysisVisitor.php

Analyze blocks of code.

- Uses `\Phan\Analysis\PreOrderAnalysisVisitor` for pre-order analysis of a node (E.g. entering a function to analyze)
- Recursively analyzes child nodes
- Uses `\Phan\Analysis\PostOrderAnalysisVisitor` for post-order analysis of a node (E.g. analyzing a statement with the updated Context and emitting issues)
- If there is more than one possible child context, merges state from them (variable types)

### Bootstrap.php

Sets up error handlers, PHP configuration, and the composer autoloader.

### CLI.php

Contains methods for parsing CLI arguments to Phan,
outputting to the CLI,
as well as helper methods to retrieve files/folders for the analyzed project.

### CodeBase.php

A CodeBase represents the known state of a code base we're analyzing.
It maps FQSENs to the representation of the object for both scanned code and internal PHP elements.
See [Developer's Guide to Phan](https://github.com/phan/phan/wiki/Developer%27s-Guide-To-Phan)

### Config.php

Program configuration. The configuration data is overridden by the analyzed project's `.phan/config.php` as well as CLI options.

### Daemon.php

Implementation of daemon mode. (Daemon for `phan_client`).
Also see `LanguageServer/`

### Debug.php

Mostly utilities for printing representations of AST nodes.
Also see `Debug/`

### ForkPool.php

Contains the ForkPool used for running multiple analysis workers(i.e. `--processes N`)

### IssueInstance.php

Contains an emitted issue with issue details (file, line, format string arguments, etc.)

### Issue.php

Contains the list of built in issue types, as well as common information (Severity, issue names, format strings, remediation difficulty, etc.)

### Memoize.php

A utility trait to memoize (cache) the result of instance methods and static methods.

### Ordering.php

This determines the order in which files will be analyzed.
(Affected by `consistent_hashing_file_order` and `randomize_file_order`.
By default, files are analyzed in the same order as `.phan/config.php`)

### Phan.php

This executes the parse, method/function, then the analysis phases.

This is the entry point of Phan's implementation.
Implementations such as `./phan` or the code climate integration call into this.

### Plugin.php

Deprecated version of plugin system, use PluginV3 instead.

### PluginV3.php

Introduced in Phan 2.0

Plugins must extend this class
(And at least one of the interfaces corresponding to plugin capabilities in the PluginV3 folder)
and return an instance of themselves.

### Prep.php

Part of a separate tool for scanning a code base. Not commonly used.

### Profile.php

For development only: Utility for profiling Phan runs. Used if the `profiler_enabled` config setting is true.

### Util.php