PHPackages                             pauldevelop/library-raml - 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. pauldevelop/library-raml

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

pauldevelop/library-raml
========================

Generate RAML documents from annotated class files.

917[2 issues](https://github.com/PaulDevelop/library-raml/issues)PHP

Since Aug 25Pushed 9y ago1 watchersCompare

[ Source](https://github.com/PaulDevelop/library-raml)[ Packagist](https://packagist.org/packages/pauldevelop/library-raml)[ RSS](/packages/pauldevelop-library-raml/feed)WikiDiscussions master Synced today

READMEChangelogDependenciesVersions (2)Used By (0)

library-raml
============

[](#library-raml)

Generate RAML documents from annotated php source files.

[RAML](http://raml.org/) is a modeling language for describing RESTful APIs and is a supplementary document that comes alongside with the API. To avoid a drifting apart of the implementation and it's documentation over time this library provides the ability to generate RAML documents based on the annotated source code files implementing the API.

This does not solve the problem completely, because the annotations need to be kept up to date as well. In return they are "nearer" coupled with the code and located in the same file, which hopefully makes it more likely for them to get updated at all.

Usage
-----

[](#usage)

The process of generating RAML documents consists of two processes: First, the parsing of source code files and looking for suitable annotations in file- and method-level docblocks. Secondly, the creation of a new RAML document based on the data the parser found in the source code files.

### Parsing

[](#parsing)

To find relevant RAML annotations in source files, use the [Parser](src/class/Parser.php) class to have them parsed.

```
$annotations = Parser::process(
    '/path/to/class.php'
);
```

The *process* method returns a [FileAnnotations](src/class/FileAnnotations.php) object, which returns the annotations in docblocks on file-, class-, member-, method- and property-level.

Supported annotations on file-level are:

- Title

    The title of the REST API. The title annotation is also used to merge related source files, which is necessary if the code which implements the API is organized in multiple files.
- Version

    The version of the REST API.
- BaseUri

    The base URI, where all resource request are based on. May contain variable parts like they are documented in the RAML specification, e. g. "[https://api.example.com/{version}](https://api.example.com/%7Bversion%7D)".
- MediaType

    The media type, the response is encoded, e. g. "application/json".
- Protocol

    The protocol that is used to access the API, e. g "HTTPS". If more than one protocol is supported, add as many protocol annotation tags as needed.
- SecurityScheme

    Describing the supported security schemes. If more than one security scheme is supported, add as many annotation tags as needed. Example for basic authentication: name="basic", type="Basic Authentication".

An example of a file-level docblock containing RAML specific annotations:

```
/**
 * @\raml\annotations\Title(title="Karmap Core API")
 * @\raml\annotations\Version(version="v1")
 * @\raml\annotations\BaseUri(baseUri="https://api.core.karmap.com/{version}")
 * @\raml\annotations\MediaType(mediaType="application/json")
 * @\raml\annotations\Protocol(protocol="HTTPS")
 * @\raml\annotations\SecurityScheme(name="basic", type="Basic Authentication")
 */

/**
 * Class-level docblock
 */
class AClass {
   ...
}
```

After specifying general information about the REST API we now proceed to describing the operations the API consists of. In most cases a REST API call will be mapped to a class function, a method. Therefor methods need to be annotated by the following tags supported on method-level:

- Resource

    Specifies the part of the URI after the base URI, that is used to name a resource, e. g. "/albums".
- HttpVerb

    A HTTP verb, that is used to access a resource, e. g. "POST".
- Description

    Description of the resource or operation.
- SecuredBy

    Use the name of one of the security schemes here, that were defined in a security scheme tag on file level, e. g. "basic".
- Parameter

    Use multiple parameter annotation tags to specify all parameters, that are necessary for an operation on the REST API. See the following source code snippet for an example.

```
...
class AClass {
    ....

    /**
     * @\raml\annotations\Resource(resource="/anonymousInterpretations")
     * @\raml\annotations\HttpVerb(verb="POST")
     * @\raml\annotations\Description(description="Create anonymous interpretation")
     * @\raml\annotations\SecuredBy(scheme="basic")
     * @\raml\annotations\Parameter(
     *   parameterType="form",
     *   name="clientCode",
     *   displayName="Client code",
     *   description="Code identifying the client",
     *   type="string",
     *   pattern="^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$",
     *   required="true",
     *   example="b4762505-b108-46a0-a4c7-f79c4b224b58"
     * )
     */
    public function doSomething(...) {
    }

    ...
}
```

### Generating

[](#generating)

To generate a RAML document, use the [Generator](src/class/Generator.php) class.

###  Health Score

22

—

LowBetter than 21% of packages

Maintenance16

Infrequent updates — may be unmaintained

Popularity12

Limited adoption so far

Community7

Small or concentrated contributor base

Maturity43

Maturing project, gaining track record

 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.

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/193919?v=4)[Rüdiger Scheumann](/maintainers/rscheumann)[@rscheumann](https://github.com/rscheumann)

---

Top Contributors

[![rscheumann](https://avatars.githubusercontent.com/u/193919?v=4)](https://github.com/rscheumann "rscheumann (9 commits)")

### Embed Badge

![Health badge](/badges/pauldevelop-library-raml/health.svg)

```
[![Health](https://phpackages.com/badges/pauldevelop-library-raml/health.svg)](https://phpackages.com/packages/pauldevelop-library-raml)
```

###  Alternatives

[pecl/mcrypt

Bindings for the libmcrypt library.

239.0k](/packages/pecl-mcrypt)[digitalkaoz/yuml-php

a PHP Adapter for http://yuml.me

321.0k](/packages/digitalkaoz-yuml-php)

PHPackages © 2026

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