1. Getting Started

Requirements

• PHP > 7.2
• MySql > 5.6
• A Apache/MySql/PHP server already installed locally
• Git and Composer
• curl, mbstring, openssl, mcrypt, gd, headers and redirect modules must be enabled in your servers

Introduction to Caligrafy

In this video we introduce you to the Caligrafy framework and to the different components that are used in it.

Join the Caligrafy Community

There are several ways for you to interact with the Caligrafy community

• github: You can always use github to stay up to date with the roadmap of Caligrafy, to post issues and to track when feature requests and issues are done
• slack: Joining our slack group is a great way to exchange with other members of the community, to get help on using the framework and to discuss any issues or features. Join our slack community
• facebook Caligrafy Group: Joining our Caligrafy group on facebook gives you more ways to interact with the community and to share success stories. Join our facebook group

Quick Installation

• Pull the code from github
• run composer install to get all the dependencies needed
• run php caligrafer.php initialize from the terminal to initialize the framework. Alternatively, you can also run .bin/caligrafer initialize
• You are good to go!
• If the quick installation does not complete successfully, proceed with the manual installation

Manual Installation

• Pull the code from github
• create a .env file by copying the example cp .env.example .env
• Change the values in .env file to match your local or production server settings
• run composer install to get all the dependencies needed
• make the folder /public/uploads/ writable if you intend to allow uploads in your application. You will need to run the command sudo chmod -R 777 /public/uploads
• You are good to go!

Different Root Folder

The default root folder is caligrafy or mvc (depending on what version of caligrafy you got). To change the name of this root folder:

• Rename the folder caligrafy to your-app-name OR git clone <caligrafy git repository> your-app-name
• Change the APP_ROOT entry in the .env file to your-app-name

Caligrafy Namespace

The Caligrafy framework is all in the namespace Caligrafy. Every class that you create will need to call the appropriate classes from the namespace.

• If you are creating a Controller:

use Caligrafy\Controller;

class MyController extends Controller {
// your code goes here
}

• If you are creating a Model:

use Caligrafy\Model;

class MyModel extends Model {
// your code goes here
}

Virtual Hosts

Creating a virtual host is optional. Caligrafy does not need the creation of virtual hosts to operate. To create a virtual host to point to the framework:

• Locate the httpd-vhosts.conf of your apache server. Usually it is located in /apache2/extra
• Add a virtual host:

<VirtualHost *:80>
    ServerName <example.loc>
    DocumentRoot "<path-to-server-root>/caligrafy"
    <Directory "<path-to-server-root>/caligrafy">
       Options FollowSymLinks
       AllowOverride All
       Require all granted
    </Directory>
</VirtualHost>

• Restart your apache server
• Add a virtual host in your machine by opening /etc/hosts file and adding the following:

127.0.0.1       example.loc

Caligrafer

Caligrafer is a command line tool that comes with Caligrafy to help you generate keys for your application and its corresponding API. Using Caligrafer is optional. Caligrafer comes prepackaged with the following commands:

• Generate Keys: Generate keys will generate an APP_KEY and an API_KEY that you can add to the .env file you created before. You can run php caligrafer.php generatekeys from the Caligrafy root.

• Generate API key: Generate a new unique API key every single time that you can distribute to third-parties. You can run php caligrafer.php generateapikey from the Caligrafy root.

Installing Caligrafy

This video explains how to install Caligrafy in different environments and it goes through a brief summary how the framework is structured

MVC Framework

This framework is based on a Model-View-Controller architecture that separates the concerns between back-end and front-end. The framework relies on the following structures:

• Database: The framework supports all the SQL databases that PDO supports. We recommend using MySql given its tight integration with PHP
• Model: The model is the back-end that contains all the data logic. It is the layer that interfaces with the storage and manages the data, whether it be a database, a JSON object. Caligrafy uses databases for data storage and therefore the model becomes the object representation of the main objects/entities of an application. In other words, every table in your database that represents an entity should have an equivalent model created in the framework
• Controller: The controller in an MVC architecture is the brain of the application that controls how the information is displayed. It is the logic layer that is responsible for interfacing with the model and rendering the data that will be displayed in the View
• View: The view is the front-end part that is responsible for displaying a user interface with the data that the controller passes on to it

Framework Fundamentals

This framework relies on several foundational concepts that are worth detailing. A good understanding of those fundamental concepts gets the developers up and running more efficiently. We will use an online catalogue of books (like Amazon) as an example throughout this documentation.

• Routes: Routing is a key element to any framework. It uses the attributes of a user request to inform the application on what action needs to be taken on what object. That process of deconstructing requests and translating them into a call to engage controllers is called Routing. For example, if you are accessing http://example.com/books from your browser, this is sending a GET request on a BOOK object. In other words, this is requesting to view a list of books. Routing is responsible for redirecting such a URL to the controller in the application that is/will be responsible for viewing the list of all books.

• Controllers: Controllers are a logical grouping of actions that can be taken on an object. For every object or entity, there should be one controller consisting of a group of actions that can be performed on that object (Create, Read, Update, Delete, etc.). Routing allows redirecting to a specific action in the controller.

• Views: Caligrafy has two different ways of building views. One for rapid development that uses a server-side template engine to render HTML pages. The other one uses Vue.js which is a more sophisticated client-side framework that is suitable for building more delightful user experiences.You could learn more about Pug (or Phug the PHP equivalent) here

• API & JSON: This framework relies on REST API fundamentals. Every route that is created could either be accessed from a browser or from any application capable of making requests. The Caligrafy View is intelligent to know whether to render a graphical user interface or a response in a JSON format.

• Models: In this framework, models are meant to be an object representation of all objects/entities of an application. For example, in an online bookstore example, books need to be represented by a Book model. Every model has a table associated with it in the database. Unlike other frameworks, this framework does not implicitly associate a model with a table (like Laravel for example). Every Model needs to be explicitly associated with a table. That gives the flexibility of separating terminology concerns between database tables and their object representations in the framework. However, all the required table columns that have no default values need to be represented in the model. Pivot tables (or many-to-many database tables) don't need to be created in the database nor represented in the Model. This framework creates these tables from the moment a many-to-many relationship is defined between Models (more on this later).

• Relationships: This framework supports one-to-one, one-to-many and many-to-many relationships between models in both directions. Each relationship is defined as part of the Model. For example, if books and publishers are two models in our example and one book has one publisher then the one-to-one relationship needs to be defined in the Book Model (hasOne relationship). Similarly, the database needs to have a foreign key in the Book table that references the id in the Publisher table. For this to happen smoothly, a naming convention needs to be followed.

• Naming conventions: This framework does not put constraints on the naming conventions as much as other frameworks. The only naming convention is around the table keys in the database.

  1. id: Every table must have id as its primary key no matter what the table name is. It is therefore recommended to avoid naming primary keys book_id or bookId. The primary key must always be id and cannot be overridden.
  2. Foreign keys: the foreign keys in the database should be of the format modelname_id. Notice that the foreign key takes the name of the Model and NOT the name of the table in the database. The foreign keys name could be overridden if need be.
  3. Pivot table naming: the framework takes care of creating the pivot tables for your convenience. The pivot table will be named depending on which model the many-to-many (belongsToMany relationship) has been called from first.

• Validation: Input validation is key to any application. This framework integrates a third-party GUMP - a very solid library - to validate all types of inputs. The validation module is capable to do 2 things: 1) Validating inputs of all types based on easy-to-define rules 2) Provide easy ways to filter data and format it based easy-to-define rules. You could learn more about GUMP here

File Structure

Understanding the framework file structure is key to understanding how to plan your development project. There are 5 main folders in the structure that you should be aware of:

1. /application: This is where most of your application logic should go. This folder is where you should create the routes, models, views and controllers. You can create any classes and organize them freely in this folder without worrying about requiring them or including them.

   This folder has 4 subfolders (models, views, controllers and config). The config folder is where the routes are defined.

   When your logic becomes too complex to hold in a Controller, you can always create new classes to organize them without having to require or include them in the classes where you intend to use them.

2. /framework: This is the underlying code for the framework. For novice programmers, you will very rarely need to change anything in this folder. However, if you need to change the way the framework operates, then this is where it can be done.

3. /public: This is where your application client-side code should go. All your scripts, stylesheets and any other resource that needs to be publicly accessible will reside in this folder. For example, any javascript or css that you need to reference from your Views (residing in application) will need to be in the public folder. Similarly, if your application supports uploading files, all uploaded files will live in the /public/uploads folder.

4. /tests: This is the folder that you could use for unit testing. Any test logic that you need to create will reside in this folder.

5. /vendor: The vendor folder contains all the third-party libraries that this framework depends on.

Next Section: Learn about Routes