• Stars
    star
    237
  • Rank 169,885 (Top 4 %)
  • Language
    PHP
  • License
    MIT License
  • Created over 5 years ago
  • Updated 3 months ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

🚔 Type check enforcement for library authors: enforces type-safety downstream

roave/you-are-using-it-wrong

Mutation testing badge Type Coverage Packagist

This package enforces type checks during composer installation in downstream consumers of your package. This only applies to usages of classes, properties, methods and functions declared within packages that directly depend on roave/you-are-using-it-wrong.

Issues that the static analyser finds that do not relate to these namespaces will not be reported.

roave/you-are-using-it-wrong comes with a zero-configuration out-of-the-box setup.

By default, it hooks into composer install and composer update, preventing a successful command execution if there are type errors in usages of protected namespaces.

The usage of this plugin is highly endorsed for authors of new PHP libraries who appreciate the advantages of static types.

This project is built with the hope that libraries with larger user-bases will raise awareness of type safety (or current lack thereof) in the PHP ecosystem.

As annoying as it might sound, it is not uncommon for library maintainers to respond to support questions caused by lack of type checks in downstream projects. In addition to that, relying more on static types over runtime checks, it is possible to reduce code size and maintenance burden by strengthening the API boundaries of a library.

Installation

This package is designed to be installed as a dependency of PHP libraries.

In your library, add it to your composer.json:

composer require roave/you-are-using-it-wrong

No further changes are needed for this tool to start operating as per its design, if your declared types are already reflecting your library requirements.

Please also note that this should not be used in "require-dev", but specifically in "require" in order for the type checks to be applied to downstream consumers of your code.

Examples

You can experiment with the following example by running cd examples && ./run-example.sh.

Given you are the author of my/awesome-library, which has following composer.json:

{
    "name": "my/awesome-library",
    "type": "library",
    "autoload": {
        "psr-4": {
            "My\\AwesomeLibrary\\": "src"
        }
    },
    "require": {
        "roave/you-are-using-it-wrong": "^1.0.0"
    }
}

Given following my/awesome-library/src/MyHelloWorld.php:

<?php declare(strict_types=1);

namespace My\AwesomeLibrary;

final class MyHelloWorld
{
    /** @param array<string> $people */
    public static function sayHello(array $people) : string
    {
        return 'Hello ' . implode(', ', $people) . '!';
    }
}

Given following downstream a/project/composer.json project that depends on your my/awesome-library:

{
    "name": "a/project",
    "type": "project",
    "autoload": {
        "psr-4": {
            "The\\Project\\": "src"
        }
    },
    "require": {
        "my/awesome-library": "^1.0.0"
    }
}

And following a/project/src/MyExample.php:

<?php declare(strict_types=1);

// notice the simple type error
echo \My\AwesomeLibrary\MyHelloWorld::sayHello([123, 456]);

Then composer install in said project will fail:

$ cd a/project
$ composer install

Loading composer repositories with package information
Updating dependencies (including require-dev)
  ... <snip>
  - Installing roave/you-are-using-it-wrong (1.0.0): ...
  - Installing my/awesome-library (1.0.0): ...
  ... <snip>

roave/you-are-using-it-wrong: checking strictly type-checked packages...
Scanning files...
Analyzing files...

ERROR: InvalidScalarArgument - a-project/src/MyExample.php:4:48 
  - Argument 1 of My\AwesomeLibrary\MyHelloWorld::sayhello expects array<array-key, string>,
    array{0:int(123), 1:int(456)} provided
echo \My\AwesomeLibrary\MyHelloWorld::sayHello([123, 456]);

$ echo $?
1

Workarounds

This package is designed to be quite invasive from a type-check perspective, but it will bail out of any checks if a psalm configuration is detected in the root of the installation/project. If that is the case, the tool assumes that the author of the project is already responsible for ensuring type-safety within their own domain, and therefore bails out without performing further checks.

As mentioned above, the design of the tool circles around raising awareness of static type usage in the PHP ecosystem, and therefore it will only give up if it is sure that library consumers are already taking care of the matter on their own.

Professional Support

If you need help with setting up this library in your project, you can contact us at [email protected] for consulting/support.

More Repositories

1

SecurityAdvisories

🔐 Security advisories as a simple composer exclusion list, updated daily
2,694
star
2

BetterReflection

🔮 Better Reflection is a reflection API that aims to improve and provide more features than PHP's built-in reflection API.
PHP
1,176
star
3

BackwardCompatibilityCheck

🆎 Tool to compare two revisions of a class API to check for BC breaks
PHP
568
star
4

no-leaks

🚰 PHPUnit Plugin for detecting Memory Leaks in code and tests
PHP
496
star
5

Dont

🚫 Small set of defensive programming utilities/traits for PHP
PHP
400
star
6

StrictPhp

🚫 ✨ ❗ AOP-based strict type checks for PHP
PHP
261
star
7

no-floaters

🔎 static analysis rules to prevent IEEE-754 floating point errors
PHP
207
star
8

FunctionFQNReplacer

PHP
158
star
9

infection-static-analysis-plugin

✅ 🐲 Static analysis on top of mutation testing - prevents escaped mutants from being invalid according to static analysis
PHP
121
star
10

psr-container-doctrine

Doctrine Factories for PSR-11 Containers
PHP
95
star
11

shorty

An asynchronous SMPP client and server built on Node.js. Shorty is sponsored and maintained by SMS Cloud, a subsidiary of Roave
JavaScript
92
star
12

DoctrineSimpleCache

Doctrine Cache adapter for PSR-16 Simple Cache
PHP
57
star
13

DocbookTool

📚 Docbook Tool for static documentation generation from Markdown files
PHP
53
star
14

Signature

✒️ Generate and verify basic signature for classes
PHP
43
star
15

behat-psr11extension

PSR-11 Container extension for Behat
PHP
40
star
16

composer-gpg-verify

🔐 📦 composer plugin to enforce GPG signatures on downloaded GIT composer packages
PHP
39
star
17

zf2-for-1

Enables using Zend Framework 2 features in a Zend Framework 1 application.
PHP
34
star
18

RoaveDeveloperTools

A PHP application visualization/debugging tool for ZendFramework/Symfony
PHP
29
star
19

psalm-html-output

Psalm HTML output format
XSLT
21
star
20

issues

Dead simple issue tracker (think standalone Github issues clone)
PHP
19
star
21

billing

open source php billing and invoicing
PHP
16
star
22

EmailTemplates

PHP
14
star
23

SecurityAdvisoriesBuilder

🔨 Build tools responsible for assembling https://github.com/Roave/SecurityAdvisories/blob/master/composer.json
PHP
10
star
24

RoaveDbCriteria

Use Doctrine Collections expressions with Zend\Db\Sql for smart criteria / filtering / query building.
PHP
6
star
25

NonceUtility

PHP
5
star
26

Assistant

Browser-based virtual assistant framework.
JavaScript
5
star
27

LaravelInfinidash

AWS Infinidash integration for Laravel applications
4
star
28

MtdTimeTracker

Simple time tracker
PHP
4
star
29

zf1-migration

Enables using newer Zend Framework features in a Zend Framework 1 application for easier migration.
PHP
3
star
30

tickets

Ticket thingy
PHP
2
star
31

roave.github.io

The Roave website.
JavaScript
2
star
32

roave.com

Roave.com website
CSS
2
star
33

DPC-Tutorial

ZF2 DPC Tutorial
PHP
2
star
34

Phlam

PHP Lambda runnner for running functions as a service on AWS
2
star
35

RoaveBot

Out little IRC campanion for #roave on Freenode.
CoffeeScript
2
star
36

RoaveTrack

This repository will somehow solve all of Roave's operational needs one day.
1
star
37

Realpath

Realpath, yo!
PHP
1
star
38

smscloud-shorty

Shorty implementation used by SMS Cloud in production.
JavaScript
1
star
39

roave.com-gh

New design for Roave.com
1
star
40

RoaveCast

Experiment(s) in real-time video/audio broadcasting to browsers.
1
star
41

demo-automatic-releases

Nothing to see here: we're just playing with github hooks
1
star