v2.x
v3.x (Latest)
v2.x
v1.x

Installation Guide

There are 2 ways to install grocery CRUD Enterprise to your project:

If you are looking for more specific installation guidance, you can also check the below tutorials:

Installation

1. Without Composer

For many people composer seems too complicated and they prefer the old fashioned copy-paste way. Also if you are using a framework that it is not requiring composer or you are using native PHP then the installation without composer is the best choice. There is nothing bad with the installation without composer, it is just that on updates it will require more manual work.

In case you prefer a video tutorial, we did create the below steps into a video see: Grocery CRUD Enterprise - Installation without composer

Step 1.

Download the zip file for installation without composer. You can also download the newest zip file from: https://www.grocerycrud.com/users . In order to have a more specific example from now on we will use the name:  grocery-crud-enterprise-v2.9.0-without-composer.zip as the zip file

Step2.

Unzip the file and you will find a file structure like that:

├── examples
│   ├── config.php
│   ├── database.php
│   ├── example.php
│   └── view.php
├── libraries
│   ├── autoload.php
│   ├── bin
│   ├── composer
│   ├── ...
│   ├── phpunit
│   ├── symfony
│   └── zendframework
└── public
    └── grocery-crud
        ├── css
        ├── fonts
        ├── images
        └── js

The folders have the following files:

  1. examples folder has a very basic example so you can simply copy the files and see it working on native PHP.
  2. libraries folder has all the PHP libraries that are required in order groceryCRUD to run. This is basically the folder vendor from composer just renamed to not have conflicts in case you want to use composer on other purposes
  3. public folder is the one that has all the JS,CSS, fonts and images that are required in order to show it on a webpage. The name is public as these files are the one that will be visible from a web browser

Before going to the next step there are 2 config files that you are required to configure. The first one is the database connection credentials. A simple database file like the below is required:

<?php
// database.php
return [
    'adapter' => [
        'driver' => 'Pdo_Mysql',
        'database' => 'db_name',
        'username' => 'db_username',
        'password' => 'db_password',
        'charset' => 'utf8'
    ]
];

As in grocery CRUD Enterprise we are using the power of Zend Framework the drivers are from Zend Framework DB version 2. For more you can see the documentation at Zend\Db\Adapter

The second configuration file is the one that you need to include for grocery CRUD. The configuration file will look like the below:

<?php
// config.php

return [
    // So far 34 languages including: Afrikaans, Arabic, Bengali, Bulgarian, Catalan, Chinese, Czech, Danish,
    // Dutch, English, French, German, Greek, Hindi, Hungarian, Indonesian, Italian, Japanese, Korean,
    // Lithuanian, Mongolian, Norwegian, Persian, Polish, Portuguese, Brazilian Portuguese, Romanian,
    // Russian, Slovak, Spanish, Thai, Turkish, Ukrainian, Vietnamese
    'default_language'  => 'English',

    // This is the assets folder where all the JavaScript, CSS, images and font files are located
    'assets_folder' => '/assets/grocery-crud/',

    // There are only three choices: "uk-date" (dd/mm/yyyy), "us-date" (mm/dd/yyyy) or "sql-date" (yyyy-mm-dd)
    'date_format' => 'uk-date',

    // The default per page when a user firstly see a list page
    'default_per_page'  => 10,

    // Having some options at the list paging. This is the default one that all the websites are using.
    // Make sure that the number of grocery_crud_default_per_page variable is included to this array.
    'paging_options' => ['10', '25', '50', '100'],

    // The environment is important so we can have specific configurations for specific environments
    'environment' => 'development',

    // Currently you can choose between 'bootstrap-v3', 'bootstrap-v4' and 'bootstrap-v5'
    'skin' => 'bootstrap-v5',

    // Automatically cleans all the inputs by trimming strings and by completely removing any HTML tag
    // to prevent XSS attacks. This is a global configuration for all the inputs so be aware in case you
    // switch this to true
    'xss_clean' => false,

    // The character limiter at the datagrid columns, zero(0) value if you don't want any character
    // limitation to the column
    'column_character_limiter' => 50,

    // Configuration for the texteditor. You can choose between 'minimal' or 'full'
    'text_editor_type' => 'full',

    // The allowed file types on upload. If the file extension doesn't exist in the array
    // it will throw an error and the upload will not be completed
    'upload_allowed_file_types' =>  [
        'gif', 'jpeg', 'jpg', 'png', 'svg', 'tiff', 'doc', 'docx',  'rtf', 'txt', 'odt', 'xls', 'xlsx', 'pdf',
        'ppt', 'pptx', 'pps', 'ppsx', 'mp3', 'm4a', 'ogg', 'wav', 'mp4', 'm4v', 'mov', 'wmv', 'flv', 'avi',
        'mpg', 'ogv', '3gp', '3g2'
    ],

    // If open_in_modal is true then all the form operations (e.g. add, edit, clone... e.t.c.) will
    // open within a modal and we will have the datagrid on the background.
    // In case you would like however to have a standalone page for all the form operations change this to false.
    'open_in_modal' => true,

    // This is the hash symbol (#) that we have at the URL in order to have tha basic operations in the URL so you
    // can navigate back to the URL that you were. For example, when you click at edit form for the id 46, the
    // URL will also change to #/edit/46 so you can also share the link.
    // In case you would like to switch this functionality to off change this to false.
    'hash_in_url' => true,

    // The button style that we have for the action buttons at the datagrid (list) page
    // Choose between 'icon', 'text', 'icon-text'
    'action_button_type' => 'icon-text',

    // The maximum number of buttons that we would like to have for the actions buttons.
    // If the number of buttons exceeds this number then the last button on the right
    // is going to change into a "More" dropdown button.
    // If the maximum number is 1 then as we only have one button as a dropdown list the translation
    // is "Actions" rather than "More"
    'max_action_buttons' => [
        'mobile' => 1,
        'desktop' => 2
    ],

    // Choose between 'left' or 'right'
    'actions_column_side' => 'left',

    // We have noticed that especially after using setRelation within a table that had more than 10K rows
    // that the datagrid was getting slower. For that reason we have optimized SQL wherever possible, and we
    // also have disabled the ordering for setRelation fields.  Keep in mind that the optimization of the queries
    // can be up to 20x faster!! Especially in big tables (e.g. with 1 million rows).
    // In case you would like though to use the ordering for the setRelation field, and you don't have big tables
    // you can set this to `false` and you will probably not notice any difference
    'optimize_sql_queries' => true,

    // Remember the quick search upon refresh. The search information is stored in the browser local storage
    'remember_quick_search' => false,
];

At the config file there are 3 basic sections that we need to be aware of:

  1. The assets_folder:  The assets folder is the folder that can publicly be accessible by the end user. These folders includes: images, JavaScript files, fonts and stylesheets files.
  2. The environment: Make sure that the development environment is the one that you are using when you are developing the project. and production is the one that is used when you are publishing the website to production.
  3. The cache: Grocery CRUD is based on cache to do as less queries to the database as possible it is strongly advised to use cache to your project. The default cache is the files cache but of course you can change the cache configurations to add a faster method to cache. All the configurations for the cache can be found at:  Zend\Cache\Storage\Adapter

Step3.

If you are using native PHP (without any framework) then you just need to copy the examples at the desired folder.

As it is always better to have a real example. Let's say that you have a PHP project that has the below structure (usually when people are using native PHP they don't use routes and hence the following structure).

├── assets
├── libs
├── index.php
├── customers.php
└── films.php

and all the JavaScript and CSS files are in the assets folder.

Copy the config files: config.php, database.php, example.php, view.php at your app folder.

So now your folder will look like this:

├── assets
├── libs
├── index.php
├── config.php
├── database.php
├── example.php
├── view.php
├── customers.php
└── films.php

And the example.php looks like this:

<?php
// example.php

include("../libraries/autoload.php");

use GroceryCrud\Core\GroceryCrud;

$database = include('database.php');
$config = include('config.php');

$crud = new GroceryCrud($config, $database);

$crud->setTable('customers');
$crud->setSubject('Customer', 'Customers');

$output = $crud->render();

if ($output->isJSONResponse) {
    header('Content-Type: application/json; charset=utf-8');
    echo $output->output;
    exit;
}

$css_files = $output->css_files;
$js_files = $output->js_files;
$output = $output->output;

include('view.php');

So now we will basically change just slightly the example.php to fit to our needs for the films.php. So first of all let's assume that the films.php has some code of your own project. For that reason, I will include the ... at the below example so you can understand that this is basically your code (e.g. header, footer, some functionality... e.t.c.).

So the final example for films.php will look like this:

<?php
// films.php

include("libraries/autoload.php");

use GroceryCrud\Core\GroceryCrud;

$database = include('database.php');
$config = include('config.php');

$crud = new GroceryCrud($config, $database);

$crud->setTable('films');
$crud->setSubject('Film', 'Films');

$output = $crud->render();

if ($output->isJSONResponse) {
    header('Content-Type: application/json; charset=utf-8');
    echo $output->output;
    exit;
}

$css_files = $output->css_files;
$js_files = $output->js_files;
$output = $output->output;

// The below include is not required. If you have another way to show:
// a. the output
// b. the CSS and JS files
// Then you can basically include the results of the output and the CSS/JS files to your own framework's output or template
include('view.php');

Now from the above code you will have a full working CRUD without the need to do anything else! You can now enjoy all the power of Grocery CRUD at the documentation (and you didn't use any terminal at all).

Troubleshooting

In case you have issues with the installation we have created a video tutorial on how to solve some common issues that you may experience:


2. Installation with composer

If you prefer the video tutorials well... we did create a video tutorial with all the below information into one video.

The most recommended way to install PHP libraries nowadays is through composer. Grocery CRUD Enterprise has private code and you should have one more step from the normal composer installations. This extra step will change at the future however this work is still in progress and currently you will need to do these 2 extra steps.

Step 1.

Download the version of groceryCRUD Enterpirse from https://www.grocerycrud.com/users or through the email that you did get. For example the file to download is: grocery-crud-enterprise-v2.9.0.zip

Step 2.

store this file through a folder that you are adding your libraries. This can be anywhere at your local environment however it is important to not rename the zip file. As this file is an artifact, we will name our folder artifacts/ you can of course use your own names like lib/ or even more specific groceryCRUD/ if you are going to use artifacts only for groceryCRUD

Step 3.

Add the below code at your composer.json

{
    "repositories": [
        {
            "type": "artifact",
            "url": "/path/to/artifacts/"
        }
    ],
    "require": {
        "grocerycrud/enterprise": "version-number"
    }
}

For example (a project that will have only groceryCRUD Enterprise as third party libraries):

{
    "repositories": [
        {
            "type": "artifact",
            "url": "artifacts/"
        }
    ],
    "require": {
        "grocerycrud/enterprise": "2.*.*"
    }
}

As many people are new to composer and sometimes is really annoying to not have real examples, I will give a more specific example of how your composer will look like. So let's say that you have installed laravel to your project. Your composer.json will look something like this (see with bold the new lines):

{
    "name": "laravel/laravel",
    "description": "The Laravel Framework.",
    "keywords": ["framework", "laravel"],
    "license": "MIT",
    "type": "project",
        "repositories": [
            {
                "type": "artifact",
                "url": "artifacts/"
            }
        ]
    "require": {
        "laravel/framework": "5.0.*",
                "grocerycrud/enterprise": "2.*.*"
    },
    "require-dev": {
        "phpunit/phpunit": "~4.0",
        "phpspec/phpspec": "~2.1"
    },
    "autoload": {
        "classmap": [
            "database"
        ],
        "psr-4": {
            "App\\": "app/"
        }
    },
    "autoload-dev": {
        "classmap": [
            "tests/TestCase.php"
        ]
    },
    "scripts": {
        "post-install-cmd": [
            "php artisan clear-compiled",
            "php artisan optimize"
        ],
        "post-update-cmd": [
            "php artisan clear-compiled",
            "php artisan optimize"
        ],
        "post-create-project-cmd": [
            "php -r \"copy('.env.example', '.env');\"",
            "php artisan key:generate"
        ]
    },
    "config": {
        "preferred-install": "dist"
    },
}

Step 4.

Now just run composer update or composer install if you are running composer for the first time on your project. Now you did install the enterprise version to your project. You will need also to copy the assets and add it to your public folder for all the JavaScript,CSS, fonts... e.t.c.

Step 5.

In order to install all your assets to your project. You need to manually copy  the folder public to your public structured project.

To have a more specific example. So let's say that you are using laravel and the structure looks like this:

├── app
│   ├── Commands
│   ├── Console
│   ├── Events
│   ├── Exceptions
│   ├── Handlers
│   ├── Http
│   ├── Providers
│   └── Services
├── bootstrap
├── config
├── database
│   ├── migrations
│   └── seeds
├── public
│   ├── css
│   └── fonts
├── resources
│   ├── assets
│   ├── lang
│   └── views
├── storage
│   ├── app
│   ├── framework
│   └── logs
├── tests
└── vendor

In that case the best place to have your public folder of groceryCRUD enterprise is at pubic->grocery-crud folder. So you will need to copy the folder from : vendor/grocerycrud/enterprise/public/grocery-crud/ to the public folder of laravel So after the copy your folder structure will look like this (in bold you can find the changed ones)

├── app
│   ├── Commands
│   ├── Console
│   ├── Events
│   ├── Exceptions
│   ├── Handlers
│   ├── Http
│   ├── Providers
│   └── Services
├── bootstrap
├── config
├── database
│   ├── migrations
│   └── seeds
├── public
│   ├── css
│   ├── fonts
|   └── grocery-crud
|   |   ├── css
|   |   ├── fonts
|   |   ├── images
|   |   └── js
├── resources
│   ├── assets
│   ├── lang
│   └── views
├── storage
│   ├── app
│   ├── framework
│   └── logs
├── tests
└── vendor

Step 6.

Now you need to create your configurations files in order to make grocery CRUD Enterprise to work. So basically there are 3 things that you will need to configured

  1. Where the public folder is
  2. The database configurations
  3. The cache folder (this is optional but it is very recommended to do it as your CRUD can be 10X faster.)

You can find all the code below of the examples at: vendor/grocerycrud/enterprise/example

There are 2 config files that you are required to configure. The first one is the database connection credentials. A simple database file like the below is required:

<?php
// database.php
return [
    'adapter' => [
        'driver' => 'Pdo_Mysql',
        'database' => 'db_name',
        'username' => 'db_username',
        'password' => 'db_password',
        'charset' => 'utf8'
    ]
];

As in grocery CRUD Enterprise we are using the power of Zend Framework the drivers are from Zend Framework DB version 2. For more you can see the documentation at Zend\Db\Adapter

The second configuration file is the one that you need to include for grocery CRUD. The configuration file will look like the below:

<?php
// config.php
return [
    // So far 34 languages including: Afrikaans, Arabic, Bengali, Bulgarian, Catalan, Chinese, Czech, Danish,
    // Dutch, English, French, German, Greek, Hindi, Hungarian, Indonesian, Italian, Japanese, Korean,
    // Lithuanian, Mongolian, Norwegian, Persian, Polish, Portuguese, Brazilian Portuguese, Romanian,
    // Russian, Slovak, Spanish, Thai, Turkish, Ukrainian, Vietnamese
    'default_language'  => 'English',

    // This is the assets folder where all the JavaScript, CSS, images and font files are located
    'assets_folder' => '/assets/grocery-crud/',

    // There are only three choices: "uk-date" (dd/mm/yyyy), "us-date" (mm/dd/yyyy) or "sql-date" (yyyy-mm-dd)
    'date_format' => 'uk-date',

    // The default per page when a user firstly see a list page
    'default_per_page'  => 10,

    // Having some options at the list paging. This is the default one that all the websites are using.
    // Make sure that the number of grocery_crud_default_per_page variable is included to this array.
    'paging_options' => ['10', '25', '50', '100'],

    // The environment is important so we can have specific configurations for specific environments
    'environment' => 'development',

    // Currently you can choose between 'bootstrap-v3', 'bootstrap-v4' and 'bootstrap-v5'
    'skin' => 'bootstrap-v5',

    // Automatically cleans all the inputs by trimming strings and by completely removing any HTML tag
    // to prevent XSS attacks. This is a global configuration for all the inputs so be aware in case you
    // switch this to true
    'xss_clean' => false,

    // The character limiter at the datagrid columns, zero(0) value if you don't want any character
    // limitation to the column
    'column_character_limiter' => 50,

    // Configuration for the texteditor. You can choose between 'minimal' or 'full'
    'text_editor_type' => 'full',

    // The allowed file types on upload. If the file extension doesn't exist in the array
    // it will throw an error and the upload will not be completed
    'upload_allowed_file_types' =>  [
        'gif', 'jpeg', 'jpg', 'png', 'svg', 'tiff', 'doc', 'docx',  'rtf', 'txt', 'odt', 'xls', 'xlsx', 'pdf',
        'ppt', 'pptx', 'pps', 'ppsx', 'mp3', 'm4a', 'ogg', 'wav', 'mp4', 'm4v', 'mov', 'wmv', 'flv', 'avi',
        'mpg', 'ogv', '3gp', '3g2'
    ],

    // If open_in_modal is true then all the form operations (e.g. add, edit, clone... e.t.c.) will
    // open within a modal and we will have the datagrid on the background.
    // In case you would like however to have a standalone page for all the form operations change this to false.
    'open_in_modal' => true,

    // This is the hash symbol (#) that we have at the URL in order to have tha basic operations in the URL so you
    // can navigate back to the URL that you were. For example, when you click at edit form for the id 46, the
    // URL will also change to #/edit/46 so you can also share the link.
    // In case you would like to switch this functionality to off change this to false.
    'hash_in_url' => true,

    // The button style that we have for the action buttons at the datagrid (list) page
    // Choose between 'icon', 'text', 'icon-text'
    'action_button_type' => 'icon-text',

    // The maximum number of buttons that we would like to have for the actions buttons.
    // If the number of buttons exceeds this number then the last button on the right
    // is going to change into a "More" dropdown button.
    // If the maximum number is 1 then as we only have one button as a dropdown list the translation
    // is "Actions" rather than "More"
    'max_action_buttons' => [
        'mobile' => 1,
        'desktop' => 2
    ],

    // Choose between 'left' or 'right'
    'actions_column_side' => 'left',

    // We have noticed that especially after using setRelation within a table that had more than 10K rows
    // that the datagrid was getting slower. For that reason we have optimized SQL wherever possible, and we
    // also have disabled the ordering for setRelation fields.  Keep in mind that the optimization of the queries
    // can be up to 20x faster!! Especially in big tables (e.g. with 1 million rows).
    // In case you would like though to use the ordering for the setRelation field, and you don't have big tables
    // you can set this to `false` and you will probably not notice any difference
    'optimize_sql_queries' => true,

    // Remember the quick search upon refresh. The search information is stored in the browser local storage
    'remember_quick_search' => false,
];

At the config file there are 3 basic sections that we need to be aware of:

  1. The assets_folder:  The assets folder is the folder that can publicly be accessible by the end user. These folders includes: images, JavaScript files, fonts and stylesheets files.
  2. The environment: Make sure that the development environment is the one that you are using when you are developing the project. and production is the one that is used when you are publishing the website to production.
  3. The cache: Grocery CRUD is based on cache to do as less queries to the database as possible it is strongly advised to use cache to your project. The default cache is the files cache but of course you can change the cache configurations to add a faster method to cache. All the configurations for the cache can be found at:  Zend\Cache\Storage\Adapter

Step 7.

And now we are ready to make grocery CRUD Enterprise to put it to work! Let's have an example of the very first use. A first example without any framework installation will look like this:

<?php
// example.php

include("vendor/autoload.php");

use GroceryCrud\Core\GroceryCrud;

$database = include('database.php');
$config = include('config.php');

$crud = new GroceryCrud($config, $database);

$crud->setTable('customers');
$crud->setSubject('Customer', 'Customers');

$output = $crud->render();

if ($output->isJSONResponse) {
    header('Content-Type: application/json; charset=utf-8');
    echo $output->output;
    exit;
}

$css_files = $output->css_files;
$js_files = $output->js_files;
$output = $output->output;

include('view.php');

And the view.php is a simple page (of course the implementation can be much better with a framework but this is just a quick example to see how easy you can install grocery CRUD Enterprise):

<!DOCTYPE html>
<html>
<head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <?php foreach($css_files as $file): ?>
        <link type="text/css" rel="stylesheet" href="<?php echo $file; ?>" />
    <?php endforeach; ?>
</head>
<body>
        <div style="padding: 20px 10px;">
            <?php echo $output; ?>
        </div>
        <?php foreach($js_files as $file): ?>
            <script src="<?php echo $file; ?>"></script>
        <?php endforeach; ?>
</body>
</html>

And congrats 🍻 ! You have installed grocery CRUD Enterprise with composer. Now you can enjoy all the power of grocery CRUD Enterprise at your project and why not create something AWESOME today!

Troubleshooting

In case you have issues with the installation we have created a video tutorial on how to solve some common issues that you may experience:


Next: API and Functions list
Next: Basic Example