logo

Installation: Creating Project and Virtual Host

To install this framework and have a fully working site you need following prerequisites:

and familiarize yourself with these concepts:

Installing Framework

Once installation requirements are met, open console and run this command:

# if your PHP version equals or exceeds 8.1 composer create-project lucinda/framework DOCUMENT_ROOT/SITE_NAME # else if your PHP version between 7.1 and 8.0 composer create-project lucinda/framework DOCUMENT_ROOT/SITE_NAME "3.4.3" # else if your PHP version smaller than 7.1 (goto: www2.lucinda-framework.com) composer create-project lucinda/framework DOCUMENT_ROOT/SITE_NAME "2.3.*"

This will install framework and all its dependencies in folder: DOCUMENT_ROOT/SITE_NAME. Now to complete installation you need to create a DOMAIN_NAME that points to that location!

Configuring Web Server

Bootstrapping is the process by which all requests to DOMAIN_NAME are routed to DOCUMENT_ROOT/SITE_NAME. In Lucinda projects (and pretty much every other framework), it is done according to following rules:

All of this is done automatically by running this command as root/superuser:

cd DOCUMENT_ROOT/SITE_NAME php configure.php vhost

This will prompt a step-by-step configuration guide. After you're all done, simply go to http://DOMAIN_NAME and continue by configuring your project. Supported operating system + software configurations:

If your OS + software combination are not in above list, you will need to configure virtual host manually but always keep this in mind: framework requires developers setting an ENVIRONMENT variable during vhost configuration! Example:

SetEnv ENVIRONMENT local

Configuring Your Project

Open your browser and visit http://DOMAIN_NAME to see a welcome page that invites you to configure your project. In order to enforce performance and modularity, project starts with MVC abilities only! To add any other, run in console (as regular user):

cd DOCUMENT_ROOT/SITE_NAME php configure.php project

This will prompt a step-by-step configuration guide useful to plug in features your project needs. Options:

  1. isREST: whether your project is a RESTful web service API. Default: 0 (no)
  2. logging: whether your project will support logging (excluding errors). Default: 1 (yes)
  3. headers: whether your project will require validation by HTTP headers. Default: 1 (yes)
    1. caching: whether your project will be able to cache response via HTTP headers through HTTP caching validation. Default: 1 (yes)
      1. no_cache: whether or not HTTP caching should be disabled by default and allowed on a route basis only. Default: 0 (no)
      2. expiration: how many seconds you want response to be served from browser cache without any server round-trip. Default: 0
    2. cors: whether your project will be able to answer OPTIONS requests for CORS validation. Default: 0 (no)
      1. allow_credentials: whether or not credentials are allowed in CORS requests. Default: 1 (yes)
      2. max_age: duration in seconds CORS responses will be cached by client browser. Default: 0
      3. allowed_request_headers: (optional) request headers that are by default allowed in your site, separated by comma
      4. allowed_response_headers: (optional) response headers that are by default exposed by your site, separated by comma
  4. internationalization: whether your project is expected to be automatically displayed into multiple languages. Default: 0 (no)
    1. defaultLocale: default locale your site will be using, following iso language and country code standard. Default: en_US
    2. detectionMethod: method by which locale will be detected by. Available options (choose index number):
      • by value of Accept-Language request header
      • by value of locale querystring parameter. Recommended if isREST=1!
      • by value of locale querystring parameter remembered into session. Recommended if isREST=0!
  5. sqlServer: whether your project will work with SQL databases. Default: 1 (yes)
    1. driver: the SQL vendor you will be using. Available options (choose index number):
      • mysql (default)
      Other popular vendors (MS SQL, PostgreSQL, Oracle) will be supported in the near future!
    2. host: ip address of server host. Default: 127.0.0.1 (localhost)
    3. port: (optional) server port. If not filled, default is used!
    4. user: user name to connect to server with
    5. password: user password to connect to server with
    6. schema: schema your app will be installed into
  6. nosqlServer: whether your project will work with key-value store NoSQL databases. Default: 0 (no)
    1. driver: the NoSQL vendor you will be using. Available options (choose index number):
      • redis (default)
      • memcache/memcached
      • couchbase
      • apc/apcu
      Other popular vendors (DynamoDB, MongoDB, CosmosDB) will be supported in the near future!
    2. host: (skipped if apc/apcu) ip address of server host. Default: 127.0.0.1 (localhost)
    3. port: (skipped if apc/apcu, optional otherwise) server port. If not filled, default is used!
    4. user: (skipped if not couchbase) user name to connect to server with
    5. password: (skipped if not couchbase) user password to connect to server with
    6. bucket: (skipped if not couchbase) bucket your app will be installed into
    7. bucket_password: (skipped if not couchbase, optional otherwise) password to connect to bucket with
  7. security: whether your project will have resources requiring authentication and authorization. Default: 0 (no)
    1. isCMS: whether your project is a CMS, requiring authentication and authorization for all resources except login. Default: 0 (no)
    2. persistenceDrivers: mediums in which logged in state will be persisted into. Available options (chosen automatically):
      • session & remember me cookie: (chosen if isREST=0) logged in user id will be saved to session and, if ticked, remember me cookie as well
      • synchronizer token: (chosen if isREST=1) logged in user id will be packed into an expiring renewable token to be sent back as header in order to keep state
    3. authenticationMethod: method by which user is allowed to authenticate with. Available options:
      • database: (default) standard form login using csrf token to fight against CSRF attacks where credentials are checked in database tables
      • database+oauth2: same as above, only also able to login via OAuth2 providers. OAuth2 login will only work once your project is reachable from world-wide-web and oauth2 tag @ stdout.xml is filled for that ENVIRONMENT!
      • xml: standard form login using csrf token to fight against CSRF attacks where credentials are checked in users tag @ stdout.xml. Not recommended, unless your site will always have same users!
    4. authorizationMethod: method by which user rights are checked for each resource (page) called. Available options (chosen automatically):
      • database: (chosen if isCMS=1) rights will be verified in database tables
      • xml: (chosen if isCMS=0) rights will be verified in routes tag @ stdout.xml
×