PHPackages                             michaeljennings/carpenter - 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. michaeljennings/carpenter

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

michaeljennings/carpenter
=========================

A PHP package to create HTML tables from a data store that can be sorted and paginated.

v1.0.11(9y ago)191.7k5[1 issues](https://github.com/michaeljennings/carpenter/issues)[2 PRs](https://github.com/michaeljennings/carpenter/pulls)MITPHPPHP >=5.4.0CI failing

Since Apr 7Pushed 6y ago4 watchersCompare

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

READMEChangelog (10)Dependencies (7)Versions (28)Used By (0)

Carpenter [![Build Status](https://camo.githubusercontent.com/6c6cfb04340b2d0633f9b9a50423ef5fcd009951a894680c7738ac3144c4032a/68747470733a2f2f7472617669732d63692e6f72672f6d69636861656c6a656e6e696e67732f63617270656e7465722e7376673f6272616e63683d6d6173746572)](https://travis-ci.org/michaeljennings/carpenter) [![Latest Stable Version](https://camo.githubusercontent.com/838326d0b1db65e6877f3da798475346bf943be8a5695d67bb1294c8e849c7de/68747470733a2f2f706f7365722e707567782e6f72672f6d69636861656c6a656e6e696e67732f63617270656e7465722f762f737461626c65)](https://packagist.org/packages/michaeljennings/carpenter) [![Coverage Status](https://camo.githubusercontent.com/df00287831f77ee4fd9bdd4af23c05cf0c9f3c68a8cad4e6950051080a1fc52c/68747470733a2f2f636f766572616c6c732e696f2f7265706f732f6d69636861656c6a656e6e696e67732f63617270656e7465722f62616467652e7376673f6272616e63683d6d617374657226736572766963653d676974687562)](https://coveralls.io/github/michaeljennings/carpenter?branch=master) [![License](https://camo.githubusercontent.com/ae3e650fb420ed40f1dffef0d8c7a311b93239442c82b88bff0d71f346980e7c/68747470733a2f2f706f7365722e707567782e6f72672f6d69636861656c6a656e6e696e67732f63617270656e7465722f6c6963656e7365)](https://packagist.org/packages/michaeljennings/carpenter)
====================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================

[](#carpenter----)

Carpenter is a PHP package to make creating HTML tables from a collection of data a breeze.

It also handles paginating, sorting, and makes tables reusable throughout your application.

Contents
--------

[](#contents)

- [Installation](#installation)
- [Laravel 5 Integration](#laravel-5-integration)
- [Laravel 4 Integration](#laravel-4-integration)
- [Creating a Table Instance](#creating-a-table-instance)
- [Table Markup](#table-markup)
    - [Class Based Tables](#class-based-tables)
- [Setting Table Data](#setting-table-data)
    - [Paginating Results](#paginating-results)
- [Adding Columns](#adding-columns)
    - [Sorting Columns](#sorting-columns)
    - [Column Labels](#column-labels)
    - [Formatting Column Data](#formatting-column-data)
- [Adding Actions](#adding-actions)
    - [Set the Action Link](#set-action-link)
    - [Set the Action Label](#set-action-label)
    - [Set the Action Attributes](#setting-action-attributes)
    - [Confirm an Action](#confirm-an-action)
- [Filtering Table Data](#filtering-table-data)
- [Rendering Tables](#rendering-tables)
    - [Rendering With a Template](#rendering-with-a-template)
    - [Getting Data From a Table Instance](#getting-data-from-a-table-instance)

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

[](#installation)

This package requires PHP 5.4+, and includes a Laravel 5 Service Provider and Facade.

To install through composer include the package in your `composer.json`.

```
"michaeljennings/carpenter": "1.0.*"

```

Run `composer install` or `composer update` to download the dependencies or you can run `composer require michaeljennings/carpenter`.

Laravel 5 Integration
---------------------

[](#laravel-5-integration)

To use the package with Laravel 5 firstly add the carpenter service provider to the list of service providers in `app/config/app.php`.

```
'providers' => array(

  Michaeljennings\Carpenter\CarpenterServiceProvider::class

);

```

Add the `Carpenter` facade to your aliases array.

```
'aliases' => array(

  'Carpenter' => Michaeljennings\Carpenter\Facades\Carpenter::class,

);

```

Publish the config files using `php artisan vendor:publish --provider="Michaeljennings\Carpenter\CarpenterServiceProvider"`

To access carpenter you can either use the Facade or the carpenter instance is bound to the IOC container and you can then dependency inject it via its contract.

```
Carpenter::get('foo');

public function __construct(Michaeljennings\Carpenter\Contracts\Carpenter $carpenter)
{
    $this->carpenter = $carpenter;
}
```

Laravel 4 Integration
---------------------

[](#laravel-4-integration)

To use the package with Laravel 4 firstly add the carpenter service provider to the list of service providers in `app/config/app.php`.

```
'providers' => array(

  'Michaeljennings\Carpenter\Laravel4ServiceProvider'

);

```

Add the `Carpenter` facade to your aliases array.

```
'aliases' => array(

  'Carpenter' => 'Michaeljennings\Carpenter\Facades\Carpenter',

);

```

Publish the config files using `php artisan config:publish michaeljennings/carpenter`

To access carpenter you can either use the Facade or the carpenter instance is bound to the IOC container and you can then dependency inject it via its contract.

```
Carpenter::get('foo');

public function __construct(Michaeljennings\Carpenter\Contracts\Carpenter $carpenter)
{
    $this->carpenter = $carpenter;
}
```

Creating a Table Instance
-------------------------

[](#creating-a-table-instance)

To get started creating tables firstly you want to make a table instance. There are two different ways to go about this.

Firstly Carpenter allows you to bind a table to a key and then retrieve it when you need it.

To bind an instance use the `add`.

```
$carpenter->add('foo', function($table) {});
```

You can then retrieve and instance by using the `get` method.

```
$table = $carpenter->get('foo');
```

Once you've retrieved a table you can run any of the table methods below to alter the table. Or if you wish you can pass a closure as a second parameter and alter the table in there.

```
$table = $carpenter->get('foo');

$table->column('bar');

$table = $carpenter->get('foo', function($table) {
	$table->column('bar');
});
```

However if you wish to make a single table instance without binding the table then you can use the `make` method.

```
$table = $carpenter->make('foo', function($table) {});
```

With the `make` method the key passed as the first argument is not used to bind the table, but it is used to keep all session data unique to the table.

Table Markup
------------

[](#table-markup)

Now that you have your table instance it's time to start defining the markup of your table. To this you may either pass an annonymous function to either the `add` or `make` method or pass it the name of class to use.

```
$carpenter->add('foo', function($table) {
	// Table logic goes here.
});

$carpenter->add('bar', Bar::class);
```

### Class Based Tables

[](#class-based-tables)

By default when using a class to define your table markup you need to provide a build method. This will be passed the table instance.

```
use Michaeljennings\Carpenter\Contracts\Table;

class Bar
{
	public function build(Table $table)
	{
		//
	}
}
```

If you want to use a different method name then you just need to specify it when you create your table instance by seperating the class name and method name with an @.

```
$carpenter->add('bar', "Bar@table");

class Bar
{
	public function table(Table $table)
	{
		//
	}
}
```

Setting Table Data
------------------

[](#setting-table-data)

At present you can either use Eloquent or CodeIgniter models, or multidimensional arrays to populate the table.

To set the model to be used use the `model` method.

```
$table->model(FooModel::class);
```

Or to use an array pass the array to the `data` method.

```
$table->data($data);
```

### Paginating Results

[](#paginating-results)

To paginate the table pass the amount of results you wish to show on each page to the `paginate` method.

```
$table->paginate(15);
```

Adding Columns
--------------

[](#adding-columns)

To add a new column or retrieve an existing column from the table use the `column` method.

```
$table->column('foo');
```

### Sorting Columns

[](#sorting-columns)

By default all columns are set to be sortable and this will be handled by carpenter. However if you wish to stop a column from being sortable the use the `unsortable` method. Or if you wish to make the column sortable use the `sortable` method.

```
$table->column('foo')->sortable();
$table->column('foo')->unsortable();
```

When sorting the package will attempt to sort by the column key, however if you are accessing a column that doesn't exist in your data store this can cause issues. An example of this would be if you were accessing a mutator in laravel.

To help get around this you can use the `sort` method to set a custom closure to be used to sort the column. The closure will be passed two parameters; the data store you are querying, and whether the sort is in descending order.

```
$table->column('foo')->sort(function($query, $desc) {
	if ($desc) {
	 	$query->orderBy('bar', 'desc');
	} else {
		$query->orderBy('bar', 'asc');
	}
});
```

### Column Labels

[](#column-labels)

By default the column will work out the label to use for the column from the column name. If the column name has an underscore then it will replace it with a space and then it will capitalise all words.

If you want to specify a specific label you can use the `setLabel` method.

```
$table->column('foo'); // Label: Foo
$table->column('foo_bar'); // Label: Foo Bar
$table->column('foo_bar')->setLabel('Baz') // Label: Baz
```

### Formatting Column Data

[](#formatting-column-data)

Occasionally you may wish to format each value in a column. For example if you were showing the price of an item then you may want to format to a currency. To do this you can use a presenter.

To get started use the `presenter` method. This is passed an annonymous function for you to format the value.

```
$table->column('price')->presenter(function($value) {
	return '&' . number_format($value, 2);
});
```

You may also wish to get data from the reset of the row. For example you may only want to show the price if the item is set to online. To do this just pass a second parameter to the closure.

```
$table->column('price')->presenter(function($value, $row) {
	if ($row->online) {
		return '&' . number_format($value, 2);
	}
});
```

Adding Actions
--------------

[](#adding-actions)

Occasionally you may need to add buttons or links to each row, or to the top of the table. To do this we use actions.

To add an action to the table, or retrieve and existing action, use the `action` method. The first parameter is a key for the action and the second is the position in the table. By default the actions go to the top of the table but to put them at the end of the row pass the position as the second argument.

```
$table->action('create');
$table->action('edit', 'row');
```

By default actions are set as buttons, however if you set an href attribute it will become an anchor. Or you can use the `setTag` method to set a custom element. When you set an element don't pass any chevrons as this will be added when the action is rendered.

```
$table->action('create')->setTag('div');
```

In the default templates the table is wrapped in a form which is where the actions post to. By default the form posts to the current url you are on, however if you wish to post to a specific url you can use the `setFormAction` method. Also if you don't want the form to post you can set the method using the `setFormMethod` method.

```
$table->setFormAction('/search');
$table->setFormMethod('GET');
```

### Set Action Link

[](#set-action-link)

To set a url for the action use the `setHref` method.

```
$table->action('create')->setHref('/create');
```

If you are using a row action you may also want to access data from the row. To this pass a closure to the `setHref`method.

```
$table->action('edit', 'row')->setHref(function($id) {
	return '/edit/' . $id;
});

$table->action('edit', 'row')->setHref(function($id, $row) {
	return '/edit/' . $row->slug;
});
```

### Set Action Label

[](#set-action-label)

To set the label for an action use the `setLabel` method.

```
$table->action('edit', 'row')->setLabel('Edit');
```

### Setting Action Attributes

[](#setting-action-attributes)

To add a class to the action use the `setClass` method.

```
$table->action('edit', 'row')->setClass('btn');
```

To set other attributes you can either use the attribute name as the method name, or use the `setAttribute` method.

```
$table->action('edit', 'row')->id('edit-item');
$table->action('edit', 'row')->setAttribute('id', 'edit-item');
```

Again like with the `setHref` method you can pass a closure as the value to get attributes from the row.

```
$table->action('edit', 'row')->setAttribute('data-id', function($id, $row) {
	return $id;
});
```

### Confirm an Action

[](#confirm-an-action)

For some actions, like deletes you may want the user to confirm that they want to run the action. To this you can use the `confirmed` method. This will leverage the default JavaScript confirm method.

The `confirmed` method takes one parameter; either the text you want the confirm box to show, or if you are using a row action then you can pass a closure to access properties from the table row.

```
$table->action('delete', 'table')->confirmed('Are you use you to delete that?');
$table->action('delete', 'row')->confirmed(function($id, $row) {
	return "Are you sure you want to delete {$row->name}?";
});
```

This will then add a confirmed attribute to the action.

```

```

Carpenter comes with a jQuery plugin to handle the confirmed functionality or you can listen for the attribute. To use the plugin just include the carpenter.js file and then run the `carpenterJs()` method on the parent element around the table.

```

    $('.table-parent').carpenterJs();

```

Other Table Methods
-------------------

[](#other-table-methods)

### Set a Table Title

[](#set-a-table-title)

To set a title for the table use the `setTitle` method. In the default templates this will be shown to the top left of the table.

```
$table->setTitle('FooBar Table');
```

Filtering Table Data
--------------------

[](#filtering-table-data)

Occasionally you may find your self wanting to query the data in the tables. To do this you can use filters.

You can add a filter either when you are creating the table markup or after you have retrieved the table instance.

To use the filter pass a closure to the `filter` method and the closure will be passed an instance of the data store you are using. If you are using a model you can use any of the methods you have access to on that model.

```
$table->filter(function($q) {
	$q->orderBy('foo');
});

$table->get('foo')->filter(function($q) {
	$q->where('foo', '=', 'bar');
});
```

Rendering Tables
----------------

[](#rendering-tables)

There are two ways to render tables; you can either use a template, or you can get the data from the table instance.

### Rendering With a Template

[](#rendering-with-a-template)

To render a table using a template call the `render` method on the table instance.

```
$table->render();
```

By default when you call the render method it will use the template set in the config file. If you want to use a template for a specific table then use the `setTemplate` method, or you can pass through a template when you call the `render` method. You can also pass through any data to the template as an array when you call the `render` method. If you want to pass through data but you the default template then just pass through null instead of the path to the template.

```
$table->setTemplate('path/to/template.php');

$table->render('path/to/template.php');
$table->render('path/to/template.php', ['foo' => 'bar']);
$table->render(null, ['foo' => 'bar']);
```

Currently Carpenter supports Laravel, CodeIgniter and a native PHP template renderer's. You can set which renderer to use in the config file.

Carpenter also comes with three default templates, but it's very simple to make your own.

### Getting Data From a Table Instance

[](#getting-data-from-a-table-instance)

### Getting the Table Columns

[](#getting-the-table-columns)

To get the table columns use the `getColumns()` method.

```
foreach ($table->getColumns() as $column) {
	//
}
```

#### Column Methods

[](#column-methods)

Get the column HTML attributes.

```
$table->getAttributes();
```

Get the column heading label.

```
$table->getLabel();
```

Check if the column is sortable.

```
$table->isSortable();
```

Get the column href.

```
$table->getHref();
```

### Getting the Table Rows

[](#getting-the-table-rows)

To get the rows use the `getRows` method.

```
foreach ($table->getRows() as $row) {
	//
}
```

You can also check if the table has any rows with the `hasRows` method.

```
if ($table->hasRows()) {
	//
}
```

#### Row Methods

[](#row-methods)

To get the cells in the row use the `getCells` method.

```
foreach ($row->getCells() as $cell) {
	echo $cell->value;
}
```

To check if the row has any actions use the `hasActions` method.

```
if ($row->hasActions()) {
	//
}
```

Then to get the actions for the row use the `getActions` method. Finally to render the action use the `render` method on the action.

```
foreach ($row->getActions() as $action) {
	echo $action->render();
}
```

### Getting Table Actions

[](#getting-table-actions)

To check if the table has any table actions use the `hasActions` method.

```
if ($table->hasActions()) {
	//
}
```

To get the actions to play at the top of the table use the `getActions` method. Then to render the action use the `render` method on the action.

```
foreach ($table->getActions() as $action) {
	echo $action->render();
}
```

### Getting the Pagination Links

[](#getting-the-pagination-links)

To check if the table has any pagination links use the `hasLinks` method.

```
if ($table->hasLinks()) {
	//
}
```

Then to get the pagination links use the `getLinks` method.

```
echo $table->getLinks();
```

### Other Table Methods

[](#other-table-methods-1)

#### Getting the Table Title

[](#getting-the-table-title)

To get the title use the `getTitle` method.

```
$table->getTitle();
```

#### Getting the Form Action

[](#getting-the-form-action)

To get the form action use the `getFormAction` method.

```
$table->getFormAction();
```

Also to get the form method use the `getFormMethod` method.

```
$table->getFormMethod();
```

###  Health Score

36

—

LowBetter than 82% of packages

Maintenance19

Infrequent updates — may be unmaintained

Popularity27

Limited adoption so far

Community16

Small or concentrated contributor base

Maturity68

Established project with proven stability

 Bus Factor1

Top contributor holds 98.3% 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 ~27 days

Recently: every ~67 days

Total

27

Last Release

3355d ago

Major Versions

v0.2.13 → v1.02015-10-11

### Community

Maintainers

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

---

Top Contributors

[![michaeljennings](https://avatars.githubusercontent.com/u/5189701?v=4)](https://github.com/michaeljennings "michaeljennings (342 commits)")[![sixteenstudio](https://avatars.githubusercontent.com/u/4678077?v=4)](https://github.com/sixteenstudio "sixteenstudio (4 commits)")[![DevKingDigital](https://avatars.githubusercontent.com/u/13821111?v=4)](https://github.com/DevKingDigital "DevKingDigital (1 commits)")[![insign](https://avatars.githubusercontent.com/u/1113045?v=4)](https://github.com/insign "insign (1 commits)")

---

Tags

laraveltable

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/michaeljennings-carpenter/health.svg)

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

###  Alternatives

[okipa/laravel-table

Generate tables from Eloquent models.

56752.8k](/packages/okipa-laravel-table)[ramonrietdijk/livewire-tables

Dynamic tables for models with Laravel Livewire

21147.4k](/packages/ramonrietdijk-livewire-tables)[gbrock/laravel-table

Table functionality for Laravel models

7644.3k](/packages/gbrock-laravel-table)[awes-io/table-builder

A component that allows creating responsive HTML tables or lists from data object

4726.1k4](/packages/awes-io-table-builder)[optimistdigital/nova-resizable

Simple Laravel Nova tool to enable column resizing

1818.9k](/packages/optimistdigital-nova-resizable)[tomshaw/electricgrid

A feature-rich Livewire package designed for projects that require dynamic, interactive data tables.

116.6k](/packages/tomshaw-electricgrid)

PHPackages © 2026

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