PHPackages                             nstory/phrappe - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. nstory/phrappe

ActiveLibrary

nstory/phrappe
==============

A fun way to run shell commands from your PHP scripts.

v1.0.0(11y ago)218MITPHP

Since Aug 6Pushed 11y ago2 watchersCompare

[ Source](https://github.com/nstory/phrappe)[ Packagist](https://packagist.org/packages/nstory/phrappe)[ RSS](/packages/nstory-phrappe/feed)WikiDiscussions master Synced 1w ago

READMEChangelog (1)Dependencies (1)Versions (2)Used By (0)

Phrappe
=======

[](#phrappe)

[![Build Status](https://camo.githubusercontent.com/4478e672aae5c1e9202fd35c3461d7df8d3bc27b1c8776184903e6ced9f19a5b/68747470733a2f2f7472617669732d63692e6f72672f6e73746f72792f706872617070652e737667)](https://travis-ci.org/nstory/phrappe)

A fun way to run shell commands from your PHP scripts.

Pronounced |frap| (the same way a New Englander pronounces "milkshake!")

Installation
------------

[](#installation)

Add something like the following to your `composer.json` file:

```
"require": {
    "nstory/phrappe": "~1"
}

```

Usage by Example
----------------

[](#usage-by-example)

```
use Phrappe\Phrappe as ph;
use Phrappe\PhrappeException;

// Phrappe let's you run and capture the output of external commands with ease

// Let's get a list of the files in the current directory
$files = ph::ls();

// The list will contain this file
assert(in_array('README.md', explode("\n", $files)));

// You can run any shell command
$gzip_version = ph::gzip('--version');

// the above command can also be run using:
$gzip_version = ph::gzip(['version' => true]);

// this is a convenient syntax for passing flags:
$jan_calendar = ph::cal(['m' => 'January']);

// combine the different syntaxes to create complex command lines:
ph::gzip(['c' => true], '-9', 'README.md');

// if the command returns a non-zero error code, an exception is thrown
try {
    ph::cat('this_file_does_not_exist');
} catch(PhrappeException $e) {
    // $e->getMessage() is stderr
    assert(preg_match('/No such file or directory/', $e->getMessage()));

    // $e->getCode() is the exist status
    assert(1 == $e->getCode());
}

// if you want to capture both stdout and stderr (this also stops
// exceptions from being thrown):
ph::$return_result = true;
$result = ph::cat('this_file_does_not_exist');
assert('' == $result->stdout);
assert(preg_match('/No such file or directory/', $result->stderr));
assert(1 == $result->exit_code);

// if static methods make you uncomfortable, instatiate it:
$ph = new Phrappe\Phrappe;
$june_1984_calendar = $ph->cal('June', '1984');

// the instance can be configured by setting a property:
$ph->return_result = true;
assert(1 == $ph->cat('this_file_does_not_exists')->exit_code);

// or at the time of instantiation
$ph = new Phrappe\Phrappe(['return_result' => true]);
assert(1 == $ph->cat('this_file_does_not_exists')->exit_code);

// one last way of running commands; this is useful when the command
// name is a reserved PHP keyword:
$ph = new Phrappe\Phrappe;
$greeting = $ph('echo', 'Hello, World!');
assert("Hello, World!\n" == $greeting);
```

CAUTION!
--------

[](#caution)

This library uses [escapeshellarg](http://php.net/manual/en/function.escapeshellarg.php) to escape special characters (quotes and such) in command parameters. This seems to work, but I would still be very cautious about passing user input to arbitrary shell commands. Programmer beware!

Similar Projects
----------------

[](#similar-projects)

- [ShellWrap](https://github.com/MrRio/shellwrap) Phrappe is a blatant copy of this library (with, what I believe believe to be, some minor improvements)
- [sh (Python)](https://pypi.python.org/pypi/sh) I believe this is the originator of the shell-commands-as-functions idea
- [Shell (Perl)](http://search.cpan.org/~ferreira/Shell-0.72/Shell.pm) Actually, this package is much older (circa 1994!)
- [ShellJS](http://documentup.com/arturadib/shelljs) While this library looks similar, it appears to actually be a Node-based quasi-reimplementation of a few Unix utilities.

License
-------

[](#license)

MIT

###  Health Score

28

—

LowBetter than 54% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity9

Limited adoption so far

Community8

Small or concentrated contributor base

Maturity63

Established project with proven stability

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Unknown

Total

1

Last Release

4302d ago

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/1010491?v=4)[Nathan Story](/maintainers/nstory)[@nstory](https://github.com/nstory)

---

Top Contributors

[![nstory](https://avatars.githubusercontent.com/u/1010491?v=4)](https://github.com/nstory "nstory (17 commits)")

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/nstory-phrappe/health.svg)

```
[![Health](https://phpackages.com/badges/nstory-phrappe/health.svg)](https://phpackages.com/packages/nstory-phrappe)
```

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)