PHPackages                             ruudk/readme-examples-sync-hook - 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. ruudk/readme-examples-sync-hook

ActiveLibrary

ruudk/readme-examples-sync-hook
===============================

Automatically sync PHP code examples with readme file

2.0.0(6mo ago)13044MITPHPPHP ^8.4CI passing

Since Aug 13Pushed 6mo ago1 watchersCompare

[ Source](https://github.com/ruudk/readme-examples-sync-hook)[ Packagist](https://packagist.org/packages/ruudk/readme-examples-sync-hook)[ RSS](/packages/ruudk-readme-examples-sync-hook/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (4)Dependencies (6)Versions (5)Used By (4)

README Examples Sync
====================

[](#readme-examples-sync)

A PHP script that automatically syncs code examples in your README.md with actual source files. This ensures your documentation always shows up-to-date, working code examples.

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

[](#installation)

```
composer require --dev ruudk/readme-examples-sync-hook
```

Usage
-----

[](#usage)

Run the script from your project root:

```
vendor/bin/readme-examples-sync
```

### Git Hook Integration

[](#git-hook-integration)

The easiest way to automatically sync your README on commit is using [Lefthook](https://lefthook.dev):

1. Install Lefthook (if not already installed):

    ```
    # macOS
    brew install lefthook
    ```
2. Create a `lefthook.yml` file in your project root:

    ```
    pre-commit:
      parallel: false
      commands:
        sync-readme-examples:
          glob:
            - "*.php"
            - "*.md"
          run: vendor/bin/readme-examples-sync
          stage_fixed: true
    ```
3. Install the hooks:

    ```
    lefthook install
    ```

That's it! Now your README will automatically sync whenever you commit changes to PHP or Markdown files.

#### Alternative: Manual Git Hook

[](#alternative-manual-git-hook)

If you prefer not to use Lefthook, you can manually create a `.git/hooks/pre-commit` file:

```
#!/bin/bash
vendor/bin/readme-examples-sync
```

Don't forget to make the hook executable:

```
chmod +x .git/hooks/pre-commit
```

How It Works
------------

[](#how-it-works)

This script scans your README.md file for special HTML comments that mark code examples:

1. **Source code sync**: Updates code blocks marked with `` with the actual content from source files
2. **Output sync** (optional): When you add `` comments, the script executes PHP files and captures their output to display results

The script automatically stages the updated README.md if changes are detected (when run in a git repository), ensuring your documentation stays in sync with your code.

### Syncing Source Code

[](#syncing-source-code)

To sync a code example with a source file, add a comment before your code block. The language identifier (e.g., `php`, `graphql`, `javascript`) is automatically inferred from the file extension:

```

```php
// This code will be replaced with content from examples/demo.php
```
```

The hook supports a wide range of file extensions including `.php`, `.graphql`, `.gql`, `.js`, `.ts`, `.json`, `.yml`, `.yaml`, `.sql`, and many more.

### Syncing Output (Optional)

[](#syncing-output-optional)

To show the output of executing a PHP file, use:

```

```php
// This will be replaced with the output from executing examples/demo.php
```
```

Example
-------

[](#example)

Here's how it looks in practice: [ruudk/code-generator](https://github.com/ruudk/code-generator).

💖 Support This Project
----------------------

[](#-support-this-project)

Love this tool? Help me keep building awesome open source software!

[![Sponsor](https://camo.githubusercontent.com/ac74b9a3a96ef54d57dab5d2199048ccc2a524cbb8bc7bb5fb76734241b776d2/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f53706f6e736f722d2545322539442541342d70696e6b)](https://github.com/sponsors/ruudk)

Your sponsorship helps me dedicate more time to maintaining and improving this project. Every contribution, no matter the size, makes a difference!

🤝 Contributing
--------------

[](#-contributing)

I welcome contributions! Whether it's a bug fix, new feature, or documentation improvement, I'd love to see your PRs.

📄 License
---------

[](#-license)

MIT License – Free to use in your projects! If you're using this and finding value, please consider [sponsoring](https://github.com/sponsors/ruudk) to support continued development.

###  Health Score

41

—

FairBetter than 89% of packages

Maintenance66

Regular maintenance activity

Popularity18

Limited adoption so far

Community13

Small or concentrated contributor base

Maturity56

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.

###  Release Activity

Cadence

Every ~23 days

Total

4

Last Release

200d ago

Major Versions

1.1.1 → 2.0.02025-10-22

### Community

Maintainers

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

---

Top Contributors

[![ruudk](https://avatars.githubusercontent.com/u/104180?v=4)](https://github.com/ruudk "ruudk (13 commits)")

---

Tags

dev

###  Code Quality

Static AnalysisPHPStan

Code StylePHP CS Fixer

Type Coverage Yes

### Embed Badge

![Health badge](/badges/ruudk-readme-examples-sync-hook/health.svg)

```
[![Health](https://phpackages.com/badges/ruudk-readme-examples-sync-hook/health.svg)](https://phpackages.com/packages/ruudk-readme-examples-sync-hook)
```

###  Alternatives

[phpstan/phpstan

PHPStan - PHP Static Analysis Tool

13.9k341.8M29.6k](/packages/phpstan-phpstan)[barryvdh/laravel-debugbar

PHP Debugbar integration for Laravel

19.1k124.3M623](/packages/barryvdh-laravel-debugbar)[phpspec/prophecy

Highly opinionated mocking framework for PHP 5.3+

8.5k551.7M682](/packages/phpspec-prophecy)[barryvdh/laravel-ide-helper

Laravel IDE Helper, generates correct PHPDocs for all Facade classes, to improve auto-completion.

14.9k123.0M686](/packages/barryvdh-laravel-ide-helper)[rector/rector

Instant Upgrade and Automated Refactoring of any PHP code

10.3k123.1M6.0k](/packages/rector-rector)[nunomaduro/collision

Cli error handling for console/command-line PHP applications.

4.6k331.8M8.5k](/packages/nunomaduro-collision)

PHPackages © 2026

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