PHPackages                             jamesflight/markaround - 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. jamesflight/markaround

ActiveLibrary

jamesflight/markaround
======================

0101[2 PRs](https://github.com/jamesflight/Markaround/pulls)PHP

Since Sep 14Pushed 4y ago1 watchersCompare

[ Source](https://github.com/jamesflight/Markaround)[ Packagist](https://packagist.org/packages/jamesflight/markaround)[ RSS](/packages/jamesflight-markaround/feed)WikiDiscussions master Synced 1mo ago

READMEChangelogDependenciesVersions (1)Used By (0)

Markaround
==========

[](#markaround)

[![Build Status](https://camo.githubusercontent.com/0a721e74b1a3e1a9d3707bb33b2224fb48191091665cc0aef6cf62038db2b88f/68747470733a2f2f7472617669732d63692e6f72672f6a616d6573666c696768742f4d61726b61726f756e642e7376673f6272616e63683d6d6173746572)](https://travis-ci.org/jamesflight/Markaround)

Markaround is a PHP library for interacting with directories of Markdown files as if they were a read only database, and imitates the syntax of Eloquent ORM from [Laravel](http://laravel.com/).

The purpose of this is to make it super easy to create blogs and document readers in PHP with no database, using directories of markdown files instead.

Bootstrapping
=============

[](#bootstrapping)

Creating a new instance: <?php

```
$config = [
    'default_path' => 'path/to/markdown/files'
];

$markaround = Jamesflight\Markaround\Factory::create($config);

```

Usage
=====

[](#usage)

Saving Markdown files:
----------------------

[](#saving-markdown-files)

Markdown files should be saved with one of the following naming conventions:

File retrievable by slug:

`file-slug.md`

File retrievable by id:

`01_.md`

File retrievable by date:

`2001-01-01.md`

These can be combined in any combination, in the order id, date, slug:

`01_2001-01-01-file-slug.md`

`01_file-slug.md`

`2001-01-01-file-slug.md`

Retrieving files:
-----------------

[](#retrieving-files)

**Retrieving all files:**

```
$posts = $markaround->all();

```

**Retrieving a file by id:**

```
$posts = $markaround->find(1);
$posts = $markaround->findOrFail(1); // Throws a MarkdownFileNotFoundException if not found

```

**Retrieving files by date**

Note: any valid PHP datetime format can be used.

```
$posts = $markaround->where('date', '1st January 2015')->get();

```

**Retrieving files by slug**

```
$posts = $markaround->where('slug', 'file-slug')->get();

```

**Retrieving the first entry from the result collection**

```
$post = $markaround->where('date', '1st January 2015')->first();
$post = $markaround->where('date', '1st January 2015')->firstOrFail(); // Throws a MarkdownFileNotFoundException if not found

```

**Retrieving where one condition or another is true**

```
$post = $markaround->where('id', 1)
            ->orWhere('id', 2)
            ->get();

```

Comparison operators
--------------------

[](#comparison-operators)

You can provide a comparison operator as the second argument in a where (or orWhere) query:

```
$posts = $markaround->where('id', '=', 1)->first();

```

Available operators are:

Equal to: `=`

Not equal to: `!=`

Less than: ``

Greater than or equal to: `>=`

Less than or equal to: `where('id', '!=', 1)->get();
$posts = $markaround->where('date', '>=', '1st January 2015')->get();

```

Custom Fields
-------------

[](#custom-fields)

At the top of each markdown file, you have the option of adding extra fields using YAML that you can also query by:

```
---
foofield: foo
barfield: bar
---
Markdown goes here

```

Supplying these custom fields allows for the following:

```
$posts = $markdown->where('foofield', '=', 'foo')->first();

```

###  Health Score

20

—

LowBetter than 14% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity6

Limited adoption so far

Community8

Small or concentrated contributor base

Maturity41

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://www.gravatar.com/avatar/566f92027ce9411d749c8eeecd21f61fb1710826af7bded17cb9878742dd3a29?d=identicon)[jamesflight](/maintainers/jamesflight)

---

Top Contributors

[![jamesflight](https://avatars.githubusercontent.com/u/5014244?v=4)](https://github.com/jamesflight "jamesflight (21 commits)")

### Embed Badge

![Health badge](/badges/jamesflight-markaround/health.svg)

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

PHPackages © 2026

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