PHPackages                             hoa/kitab - 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. [Testing & Quality](/categories/testing)
4. /
5. hoa/kitab

AbandonedArchivedLibrary[Testing & Quality](/categories/testing)

hoa/kitab
=========

Kitab is the ideal companion for Documentation-Driven Quality: Render and Test your documentation.

0.12(8y ago)792.5k↓12.5%8[4 issues](https://github.com/hoaproject/Kitab/issues)[2 PRs](https://github.com/hoaproject/Kitab/pulls)1BSD-3-ClausePHPPHP >=7.0

Since Jul 5Pushed 5y ago6 watchersCompare

[ Source](https://github.com/hoaproject/Kitab)[ Packagist](https://packagist.org/packages/hoa/kitab)[ Docs](https://hoa-project.net/)[ RSS](/packages/hoa-kitab/feed)WikiDiscussions master Synced 3w ago

READMEChangelog (10)Dependencies (10)Versions (16)Used By (1)

 [![](https://raw.githubusercontent.com/hoaproject/Kitab/master/resource/logo.svg?sanitize=true)](https://raw.githubusercontent.com/hoaproject/Kitab/master/resource/logo.svg?sanitize=true)

---

 [![Build status](https://camo.githubusercontent.com/ea0fddfb0cd81c46e6cfde8f98cfe4f885320cad2fbbb395c5ac09f40356fd63/68747470733a2f2f696d672e736869656c64732e696f2f7472617669732f686f6170726f6a6563742f4b697461622f6d61737465722e737667)](https://travis-ci.org/hoaproject/Kitab) [![Packagist](https://camo.githubusercontent.com/8785d1f6e15d83903b7aacea0f5cca2690bad98a09d5acdbb8c60f6361c5477b/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f686f612f6b697461622e737667)](https://packagist.org/packages/hoa/kitab) [![License](https://camo.githubusercontent.com/dfd5c13fc9552e5624bfc4f7bead18de60495e1330e650742c4f2aef42fb989b/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f686f612f6b697461622e737667)](https://hoa-project.net/LICENSE)

 **Kitab** is the ideal companion for **Documentation-Driven Quality** for PHP programs.

 Made with ❤️ by [![Hoa](https://camo.githubusercontent.com/2b5c32c5d4bc5e9298821b22d364a522e2dbc0295c1c011b1f9f86a4d07df07e/68747470733a2f2f7374617469632e686f612d70726f6a6563742e6e65742f496d6167652f486f612e737667)](https://hoa-project.net)

The goal of Kitab is twofold, **render** and **test** the documentation:

1. Generate a quality and searchable documentation based on your code. The documentation inside your code is compiled into static HTML files with a powerful static search engine,
2. Test the documentation itself. Indeed, a documentation contains examples, and these examples are compiled into test suites that are run directly to ensure the examples are still up-to-date and working.

Kitab ([كتاب](https://ar.wiktionary.org/wiki/%D9%83%D9%90%D8%AA%D9%8E%D8%A7%D8%A8)) means “book” in Arabic. It should pronounced /kitaːb/.

Static documentation
====================

[](#static-documentation)

Kitab is able to compile the documentation inside your code into static HTML files. A carefully crafted design is provided to ensure a great look for your documentation. This is possible to customize the logo, the project name, etc.

A static search engine is compiled specifically for your documentation. It contains all the modern features we can expect from a search engine, like tokenizing, stemming, stop word filtering, term frequency-inverse document frequency (TF-ID), inverted index etc. The search engine database is pre-computed and optimized to load as fast as possible.

The more your documentation provides details and smart vocabulary, the more the search engine will be able to provide relevant results.

The following command line compiles the documentation from your code in `src` into HTML files stored in `doc`:

```
$ ./bin/kitab compile --open --with-composer --output-directory doc src
```

The `--with-composer` option asks Kitab to use Composer for PSR-4 mapping definitions. This is useful to map `README.md` files to namespace directories, more below. The `--open` option opens the documentation in your default browser as soon as it is generated successfully.

DocTest
=======

[](#doctest)

Documentation test suites, aka DocTest, are generated based on the examples present in your documentation. Examples are compiled into test suites and executed on-the-fly. A cache is generated to avoid to re-compile examples into test suites each time.

For instance, the following example will succeed:

```
/**
 * Classical sum of two integers.
 *
 * # Examples
 *
 * ```php
 * $x = 1;
 * $y = 2;
 *
 * assert(3 === sum($x + $y));
 * ```
 */
function sum(int $x, int $y): int
{
    return $x + $y;
}
```

The following command line generates and executes the documentation test suites from the `src` directory:

```
$ ./bin/kitab test src
```

Behind the scene, Kitab uses [the atoum test framework](http://atoum.org).

Dependencies
============

[](#dependencies)

Kitab requires [PHP](http://php.net/)and [NodeJS](https://nodejs.org/) to be installed: PHP because this is a PHP program, and NodeJS to pre-compile the static search engine (which is written in [Elm](http://elm-lang.org/)).

Standards and formats
=====================

[](#standards-and-formats)

Kitab expects documentation in your PHP code to be written in [CommonMark](http://commonmark.org/) (a standard variant of Markdown). It can be mixed with [HTML](https://w3.org/TR/html5/).

Each block of documentation can declare sections, and any kind of CommonMark elements, like:

```
/**
 * This is a block of documentation, attached to a PHP class.
 *
 * # Examples
 *
 * An example illustrates how to use the documented entity, here the
 * class `C`.
 *
 * ```php
 * $c = new C();
 * ```
 */
class C { }
```

There are only 2 special section names: *Examples*, and *Exceptions*. Use them to introduce one or more examples, and exceptions explanations. This is a common standard used by many other tools.

Any kind of entities can be documented: Classes, interfaces, traits, class attributes, constants, methods, and functions.

Namespaces cannot be documented directly from the code, because of the way they are declared (entities are declared inside a namespace; the namespace is not declared as is). However, they can be documented through special files, named `README.md`. If your code follows [the PSR-4 specification](http://www.php-fig.org/), then run Kitab with the `--with-composer` option to specify the location of the `composer.json` file of your project in order to allow Kitab to automatically find PSR-4 mappings. These mappings are necessary to transform a namespace into a path to a directory. For each directory representing a namespace, if a `README.md` file exists, then it will be used as the documentation of this particular namespace. For instance, `Kitab\` maps to `src/`, so the documentation for the [`Kitab`\\`Compiler`](kitab/compiler/index.html) namespace is expected to be find in the `src/Compiler/README.md` file, that simple. This is pretty straightforward at usage.

Entity and namespace documentations are inserted at the top of their respective documentation page. This is the introduction. The rest of the page contains information about the entity or the namespace.

Block of codes
--------------

[](#block-of-codes)

Documentation can contain block of codes. This is possible to specify the type of the block with this standard notation:

```
```type
code
```

```

where `type` can be `php`, `http`, `sh`, `html`, `css` etc.

The type has 2 impacts:

1. It specifies the syntax highlighting when rendering the documentation in HTML,
2. It is an identifier for a potential code block handler. A code block handler is responsible to compile a code block content into a valid test.

Indeed, all code blocks inside the Examples and Exceptions Sections can be compiled into test suites with the `./bin/kitab test`command. For instance, with the `php` code block type, one can specify the expectation of the test case:

- `php` indicates the test case must be a success,
- `php,ignore` indicates the test case must be skiped (only rendered, not tested),
- `php,must_throw` indicates the test case must throw an exception of any kind,
- `php,must_throw(E)` indicates the test case must throw an exception of kind `E`.

Consequently, the following example will be a success:

```
/**
 * Generate a runtime exception.
 *
 * # Examples
 *
 * ```php,must_throw(RuntimeException)
 * panic('Hello World');
 * ```
 */
function panic(string $message): RuntimeException
{
    throw new RuntimeException($message);
}
```

Extensible
----------

[](#extensible)

It is possible to write specific code block handlers. It means that you can write extensions to Kitab to compile your documentation into specific tests. To learn more, check the `Kitab\Compiler\Target\DocTest\CodeBlockHandler\Definition` interface and implementations.

Configurations
==============

[](#configurations)

It is possible to configure Kitab with external PHP files. The file names are free, but we recommend the following:

- `.kitab.target.html.php` to configure the compilation of the documentation to HTML,
- `.kitab.target.doctest.php` to configure the test of the documentation.

Both files must respectively return an instance of the `Kitab\Compiler\Target\Html\Configuration` and `Kitab\Compiler\Target\DocTest\Configuration` classes.

The following example illustrates a common `.kitab.target.html.php`file:

```
$configuration = new Kitab\Compiler\Target\Html\Configuration();

$configuration->defaultNamespace = 'Kitab';
$configuration->logoURL          = 'https://example.org/logo.png';
$configuration->projectName      = 'Kitab';
$configuration->composerFile     = __DIR__ . '/composer.json';

return $configuration;
```

The following example illustrates a common `.kitab.target.doctest.php`file:

```
$configuration = new Kitab\Compiler\Target\DocTest\Configuration();

$configuration->autoloaderFile      = __DIR__ . '/vendor/autoload.php';
$configuration->concurrentProcesses = 4;

return $configuration;
```

Both commands `kitab compile` and `kitab test` accept an option named `--configuration-file` to use a particular configuration file for the defaults, e.g.:

```
$ ./bin/kitab compile --configuration-file .kitab.target.html.php --output-directory doc src
```

###  Health Score

34

—

LowBetter than 75% of packages

Maintenance19

Infrequent updates — may be unmaintained

Popularity36

Limited adoption so far

Community12

Small or concentrated contributor base

Maturity56

Maturing project, gaining track record

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

Every ~25 days

Recently: every ~36 days

Total

12

Last Release

3000d ago

PHP version history (2 changes)0.1PHP >=7.1

0.3PHP >=7.0

### Community

Maintainers

![](https://www.gravatar.com/avatar/a410060743cec0e0d8654661b726a7a25f5888f18059d4c942a8fd9a8128f0da?d=identicon)[Hoa](/maintainers/Hoa)

---

Tags

documentationhoaphpqualitytestsearchtestdocumentationlibrarygenerate

### Embed Badge

![Health badge](/badges/hoa-kitab/health.svg)

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

###  Alternatives

[mockery/mockery

Mockery is a simple yet flexible PHP mock object framework

10.7k516.1M26.1k](/packages/mockery-mockery)[behat/behat

Scenario-oriented BDD framework for PHP

4.0k100.2M2.1k](/packages/behat-behat)[tempest/framework

The PHP framework that gets out of your way.

2.2k31.1k12](/packages/tempest-framework)[helsingborg-stad/municipio

A bootstrap theme for creating municipality sites.

4028.3k10](/packages/helsingborg-stad-municipio)[leanphp/behat-code-coverage

Generate Code Coverage reports for Behat tests

50360.7k2](/packages/leanphp-behat-code-coverage)[quizlet/hammock

Hammock is a stand-alone mocking library for Hacklang.

27445.5k](/packages/quizlet-hammock)

PHPackages © 2026

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