https://github.com/box/augmented_types
A PHP extension to enforce parameter and return type annotations
https://github.com/box/augmented_types
Last synced: about 1 year ago
JSON representation
A PHP extension to enforce parameter and return type annotations
- Host: GitHub
- URL: https://github.com/box/augmented_types
- Owner: box
- License: apache-2.0
- Created: 2014-01-30T22:36:34.000Z (over 12 years ago)
- Default Branch: master
- Last Pushed: 2015-01-15T00:30:21.000Z (over 11 years ago)
- Last Synced: 2025-04-09T13:46:51.789Z (about 1 year ago)
- Language: C++
- Homepage:
- Size: 1.11 MB
- Stars: 164
- Watchers: 14
- Forks: 11
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# Augmented Types
Augmented Types is a PHP extension that enforces PHPDoc-style type annotations at runtime. It is compatible with opcode cachers and allows for selective enforcement of function type annotations, enabling incremental gains in type safety with a minimal performance cost.
## Usage
Augmented Types requires that all type-enforced functions and methods be annotated with valid PHPDoc that specifies a type for the return value and every argument, like so:
```php
/**
* @param int $a
* @return float[]
*/
function foo ($a) {
echo "You passed in the integer $a";
return [$a * 1.0, $a * 2.718];
}
```
At runtime, if any type differs from the expected type on a type-enforced function, Augmented Types will throw a fatal error. More information on [the type system](https://github.com/box/augmented_types/wiki/The-Type-System) and [type annotation requirements](https://github.com/box/augmented_types/wiki/Type-Annotation-Requirements) can be found on the wiki.
Augmented Types' master INI setting is `augmented_types.enforce_by_default`, which is considered to be 0 if not set. That means, by default, Augmented Types will _only_ enforce type annotations on a given function if the file or directory the function is contained in is added to a whitelist. Augmented Types allows you to both whitelist and blacklist files and directories for enforcement.
Alternatively, if you'd like to enable Augmented Types enforcement on all files, add `augmented_types.enforce_by_default=1` to your php.ini.
More information about whitelisting and blacklisting can be found [on the wiki](https://github.com/box/augmented_types/wiki/Whitelisting-and-Blacklisting).
## Installation
Compilation of Augmented Types is fairly straight-forward on any Unix-based system. Instructions can be found on the [installation wiki page](https://github.com/box/augmented_types/wiki/Installation) on how to compile, install, and properly configure Augmented Types. Unfortunately, at this time we do not support compilation on Windows systems, although we gladly welcome contributions to help support all environments.
## FAQ
The [FAQ](https://github.com/box/augmented_types/wiki/FAQ) has answers to many common questions, including how we use Augmented Types at Box and its performance characteristics. Information on contributing can be found [here](/CONTRIBUTING.md).
## Copyright and License
Copyright 2014 Box, Inc. All rights reserved.
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.