Skip to content

1.2 Lecture 2: Installation and Basics of the MVC framework

Jump to bottom
DA edited this page May 17, 2020 · 11 revisions

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 the Caligrafy official github by typing the following command in the terminal: git clone git@github.com:DoryAzar/caligrafy.git <optional: different folder_name>
  • 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 the Caligrafy official github by typing the following command in the terminal: git clone git@github.com:DoryAzar/caligrafy.git <optional: different folder_name>
  • 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 an 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 layer that interfaces with the database. It is the object representation of the main objects/entities of your 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 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 spending time on. A good understanding of those fundamental concepts will get you up and running quicker. 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 Request to inform the application on what action needs to be taken on what object. That process of deconstructing the Request and translating them into a call to engage controllers from your application is called Routing. For example, if you are accessing http://example.com/books from your browser, this is sending a GET request on the BOOK object. In other words, this is requesting to View a list of books. In the absence of any other additional information, this is suggesting View a list of ALL the books. Relying solely on the Request gives us the intent. Routing is responsible for redirecting such a URL to the controller in your 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. In our example, there should be one book controller and in it 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: This framework uses Pug to render Views. Pug is a solid library that dynamically renders HTML content. You could learn more about Pug (or Phug the PHP equivalent) here

  • API & JSON: This framework is relies on a REST-API fundamentals. Every route that is created could either be accessed from your HTML application or from an API Request.

  • Models: In this framework Models are meant to be an object representation of all objects/entities that define your application. In our example, books need to be represented by Book model. Every Model has a table associated to 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.

Clone this wiki locally