view-components/grids

Flexible Framework-agnostic Data Grids for PHP

Grids

, _(*1)

Flexible Framework-agnostic Data Grids for PHP

This project is a successor of nayjest/grids (Data Grids Framework for Laravel).

This package is framwork-agnostic in sense of both backend and frontend frameworks, i.e.: * You can use it with any PHP framework or without it. Integration packages will help you to use facilities of popular PHP frameworks. * Don't worry about fitting markup to your favorite CSS framework. Just describe grid structure and add one of available customizations that will apply framework-specific modifications to markup., _(*2)

Project status: beta since 2016-03-31, _(*3)

Have questions? Ask in issue-tracker., _(*4)

Screenshot:, _(*5)

, _(*6)

Table of Contents

• Features
• Requirements
• Installation
  • Installing into Existing Project
  • Installing as Stand-alone Project
• Integrations
• Usage
• Demo Application
  • Working Demo Deployed to Heroku
  • Running Demo Application Locally
• Documentation
• Testing
• Contributing
• Security
• License

Features

• Flexible component architecture
• Can be used with wide variety of data sources (php array, PDO database connection, Laravel ActiveRecord or QueryBuilder, Doctrine DBAL Query builder, etc)
• Themes / Customizations / Styling
• Can be used with any PHP framework, has integration packages for popular frameworks.
• Don't worry about fitting markup for your favorite CSS framework. Just describe grid structure and components and then apply customization. This package is framework-agnostic in sense of frontend frameworks and bundled with themes for Twitter Bootstrap, Foundation, Semantic UI
• Alot of components ready to use: filters, sorting, totals, row details, pagination, CSV export
• User-friendly for developers (documentation in progress)

Requirements

• PHP 5.5+ (hhvm & php7 are supported)

Installation

Installing into Existing Project

The recommended way of installing the component is through Composer., _(*7)

Run following command from your project folder:, _(*8)

composer require view-components/grids

Add-ons

If you use Laravel, install also eloquent-data-processing package., _(*9)

composer require view-components/eloquent-data-processing

This will give possibility to use Eloquent models and query builder instances as data source for grid., _(*10)

For Doctrine users, there is doctrine-data-processing package available., _(*11)

composer require view-components/doctrine-data-processing

Installing as Stand-alone Project

For running tests and demo-application bundled with this package on your system you need to install it as stand-alone project., _(*12)

composer create-project view-components/grids

This is the equivalent of doing a git clone followed by a "composer install" of the vendors. Composer will automatically run 'post-create-project-cmd' command and that will call interactive installation., _(*13)

If you want to use default settings and run it silently, just add --no-interaction option., _(*14)

If you already cloned this repository, or you want to reinstall the package, navigate to the package folder and run composer create-project command without specifying package name., _(*15)

If you are sure that you don't need to reinstall composer dependencies, you can execute only bundled installer: composer run post-create-project-cmd, _(*16)

This kind of installation has additional requirements: * ext-curl * ext-pdo_sqlite, _(*17)

Integrations

Usage

Basic example:, _(*18)

$provider = new DbTableDataProvider($pdoConnection, 'my_table');
$input = new InputSource($_GET);

// create grid
$grid = new Grid(
    $provider,
    // all components are optional, you can specify only columns
    [
        new TableCaption('My Grid'),
        new Column('id'),
        new Column('name'),
        new Column('role'),
        new Column('birthday'),
        (new Column('age'))
            ->setValueCalculator(function ($row) {
                return DateTime
                    ::createFromFormat('Y-m-d', $row->birthday)
                    ->diff(new DateTime('now'))
                    ->y;
            })
            ->setValueFormatter(function ($val) {
                return "$val years";
            })
        ,
        new DetailsRow(new SymfonyVarDump()), // when clicking on data rows, details will be shown
        new PaginationControl($input->option('page', 1), 5), // 1 - default page, 5 -- page size
        new PageSizeSelectControl($input->option('page_size', 5), [2, 5, 10]), // allows to select page size
        new ColumnSortingControl('id', $input->option('sort')),
        new ColumnSortingControl('birthday', $input->option('sort')),
        new FilterControl('name', FilterOperation::OPERATOR_LIKE, $input->option('name')),
        new CsvExport($input->option('csv')), // yep, that's so simple, you have CSV export now
        new PageTotalsRow([
            'id' => PageTotalsRow::OPERATION_IGNORE,
            'age' => PageTotalsRow::OPERATION_AVG
        ])
    ]
);

// now you can render it:
echo $grid->render();
// or even this way:
echo $grid;

//  but also you can add some styling:
$customization = new BootstrapStyling();
$customization->apply($grid);
echo $grid;

Demo Application

This package bundled with demo-application., _(*19)

Source code of demos available here, _(*20)

Working Demo Deployed to Heroku

Travis CI automatically deploys web-application bundled with this package to Heroku., _(*21)

Here you can see working demos: http://vc-grids.herokuapp.com/, _(*22)

First run may be slow because Heroku shutting down workers when there is no traffic and starts it again on first visit, _(*23)

Running Demo Application Locally

To run it locally, you must install this package as stand-alone project with dev-dependencies., _(*24)

Then, run web-server from the package directory with the following command:, _(*25)

composer serve

This command uses web-server bundled with PHP., _(*26)

Now, open http://localhost:8000 in the browser (for Windows users it will be opened automatically after starting web-server)., _(*27)

Documentation

• Grids Cookbook
• ViewComponents / Components Overview
• ViewComponents / Cookbook

Testing

This application bundled with unit and acceptance tests created with PHPUnit., _(*28)

To run tests locally, you must install this package as stand-alone project with dev-dependencies., _(*29)

Command for running unit and acceptance tests:, _(*30)

composer test

Command for checking code style:, _(*31)

composer cs

Contributing

Please see Contributing Guidelines and Code of Conduct for details., _(*32)

Security

If you discover any security related issues, please email mail@vitaliy.in instead of using the issue tracker., _(*33)

License

© 2015—2016 Vitalii Stepanenko, _(*34)

Licensed under the MIT License., _(*35)

Please see License File for more information., _(*36)