PHPackages                             nubs/bizgolf - 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. [Utility & Helpers](/categories/utility)
4. /
5. nubs/bizgolf

ActiveLibrary[Utility & Helpers](/categories/utility)

nubs/bizgolf
============

A library that interacts with Docker in order to execute user's code golf submissions and verify their correctness.

161[7 issues](https://github.com/nubs/bizgolf/issues)PHP

Since Feb 6Pushed 10y ago1 watchersCompare

[ Source](https://github.com/nubs/bizgolf)[ Packagist](https://packagist.org/packages/nubs/bizgolf)[ RSS](/packages/nubs-bizgolf/feed)WikiDiscussions master Synced 2mo ago

READMEChangelogDependenciesVersions (1)Used By (0)

BizGolf
=======

[](#bizgolf)

A library that interacts with [Docker](http://www.docker.io) in order to execute user's [code golf](http://en.wikipedia.org/wiki/Code_golf) submissions and verify their correctness.

What is Code Golf?
------------------

[](#what-is-code-golf)

Code golf is a programming competition where the aim is to solve problems using the fewest bytes of code. This tests programmers logic skills and the knowledge of their programming languages in all the corner cases of syntax.

What is BizGolf?
----------------

[](#what-is-bizgolf)

Bizgolf is an attempt to create an open source codegolf library and hosting platform for hosting standalone code golf events.

Ideas for events:

- Annual code golf tournament with one active hole at a time.
- Have a competition between 2 or more development teams.
- During a hackathon, there could be an ongoing codegolf tournament on the side.

Languages Supported
-------------------

[](#languages-supported)

Right now, just PHP is available, but [adding](#new-languages) other languages shouldn't be too difficult. The tricky bit is just in locking the language features down like shell execution, web access, etc., that would allow for "cheating".

- [PHP](http://www.php.net) - versions [5.4.16](http://www.php.net/ChangeLog-5.php#5.4.16) and [5.5.0](http://www.php.net/ChangeLog-5.php#5.5.0)

Included Holes
--------------

[](#included-holes)

A growing list of holes will be included along with this library, making it easy to try out and run an impromptu event. [Adding](#new-holes) your own holes is easy too, though.

- [99 Bottles of Beer on the Wall](holes/99-bottles-of-beer-on-the-wall.php)
- [Fizzbuzz](holes/fizzbuzz.php)
- [Hello World](holes/hello-world.php)
- [Upper Case Words](holes/ucwords.php)

Requirements
------------

[](#requirements)

The host library is currently written in PHP, but it's a small library that could be easily ported to another language. Some features from php 5.4 are used, so make sure you are running at least 5.4.

Required libraries are pulled in using [Composer](http://getcomposer.org). They will be automatically installed if you use composer to install the library and use its autoloader.

For executing user code, [Docker](http://www.docker.io) is used. It has somewhat strict requirements, but people have gotten it working on a wide number of environments and there is ongoing efforts to make it operable on many more environments. Take a look at its documentation for getting it installed on your system.

No additional requirements should be needed, docker takes care of getting the execution environment setup for each language.

Library Usage
-------------

[](#library-usage)

The expected usage of this library is through the included php functions. Add this library to your php project via composer:

```
{
    "require": {
        "nubs/bizgolf": "dev-master"
    }
}
```

Composer's autoloader will automatically include the functions for use in your project. The functions' APIs are below.

```
/**
 * Creates a docker image based on the requested language with the given user
 * script added to the image for execution.
 *
 * @param string $languageName One of the supported languages.
 * @param string $script The file path to the user's submission to test.
 * @param string|null $constantName The name of the constant to set, if a
 *     constant is being used.
 * @param mixed|null $constantValue The value of the constant to set, if a
 *     constant is being used.
 * @return array A description of the docker image that was created.
 * @throws Exception if unable to create docker image
 */
function createImage(
    $languageName,
    $script,
    $constantName = null,
    $constantValue = null
);

/**
 * Loads the hole configuration for an included hole.  If you want to add your
 * own holes outside of this project, you don't need to call this function.
 *
 * @param string|callable $hole One of the included holes specified by name, or
       a hole specification wrapped in a closure.
 * @return array The hole's configuration.  Included fields:
 *     string|null constantName The name of the constant that will hold
 *         input.
 *         This may be a callable as well, with 0 arguments.
 *     array constantValues The different values of input to test.
 *         This may be a callable as well, with 0 arguments.
 *     callable|null trim What kind of trim to apply to the results
 *         before comparison.
 *     string sample The expected output for the hole.
 *         This may be a callable as well, with 1 argument containing the
           constant value for input.
 */
function loadHole($hole);

/**
 * Judges the user submission for a language against the given hole
 * configuration.
 *
 * @param array $hole The hole's configuration.  @see loadHole() for details.
 * @param string $languageName One of the supported languages.
 * @param string $script The file path to the user's submission to test.
 * @return array The results of judging the submission and the details of the
 *     submission's last run.  Included fields:
 *     bool result Whether the submission passed the tests or not.
 *     int exitStatus The exit status of the command.
 *     string output The output, trimmed according to the rules of the hole.
 *     string sample The expected output, trimmed according to the rules of
 *         the hole.
 *     string stderr The stderr output.
 *     string|null constantName The constant's name, if used.
 *     mixed|null constantValue The constant's value, if used.
 */
function judge(array $hole, $languageName, $script);
```

Here's an example of how it could be used to judge a user's submission:

```