A PHP extension to enforce parameter and return type annotations
C++ PHP Bison Other
Latest commit eed4bdf Jan 14, 2015 @jmarrama jmarrama Add in white+blacklist configuration to ini directives
This commit adds two new ini directives, 'augmented_types.whitelist'
and 'augmented_types.blacklist' that take colon-seperated lists of
paths to add to the blacklist and whitelist on request start.

This also bumps the bugfix version number
Permalink
Failed to load latest commit information.
docs/stubs First commit for open source. Starting at v0.5.0 Jan 30, 2014
misc Constructors with no args are now enforced Jul 17, 2014
phpdoc Update scanner.l Jan 8, 2015
stress First commit for open source. Starting at v0.5.0 Jan 30, 2014
tests Add in white+blacklist configuration to ini directives Jan 14, 2015
.gitignore Add a temporary test file to gitignore Jan 31, 2014
CONTRIBUTING.md First commit for open source. Starting at v0.5.0 Jan 30, 2014
LICENSE First commit for open source. Starting at v0.5.0 Jan 30, 2014
Makefile-parser-targets.frag First commit for open source. Starting at v0.5.0 Jan 30, 2014
PHPDoc_Bison_Compiler.cc Constructors with no args are now enforced Jul 17, 2014
PHPDoc_Bison_Compiler.h Constructors with no args are now enforced Jul 17, 2014
PHPDoc_Compiler.h First commit for open source. Starting at v0.5.0 Jan 30, 2014
README.md Clarified enabling option Feb 1, 2014
augmented_annotation_compiler.cc Perpare compiler state before each compilation pass Jul 22, 2014
augmented_annotation_compiler.h Perpare compiler state before each compilation pass Jul 22, 2014
augmented_types.cc Perpare compiler state before each compilation pass Jul 22, 2014
augmented_types_module.cc Add in white+blacklist configuration to ini directives Jan 14, 2015
augmented_types_module.h First commit for open source. Starting at v0.5.0 Jan 30, 2014
augmented_util.cc Advance class and function table pointers every compilation invocation Jul 14, 2014
augmented_util.h First commit for open source. Starting at v0.5.0 Jan 30, 2014
config.m4 Make flex and bison required during configuration step Feb 1, 2014
php_augmented_types.h Add in white+blacklist configuration to ini directives Jan 14, 2015

README.md

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:

/**
* @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 and 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.

Installation

Compilation of Augmented Types is fairly straight-forward on any Unix-based system. Instructions can be found on the installation wiki page 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 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.

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.