Welcome to Lucinda 3.0! This ultra high performance PHP framework, developed with simplicity and modularity at its foundation, functions as an XML-based contract of completely independent APIs:
- STDOUT MVC API: handles HTTP requests into responses using MVC paradigm
- STDERR MVC API: handles errors or uncaught exceptions into reports and responses using MVC paradigm
- View Language API: templates HTML views using a language extending HTML standard, similar to Java's EL & JSTL
- Logging API: logs messages to a storage medium
- SQL Data Access API: connects to SQL vendors (eg: MySQL), executes queries and parses results on top of PDO
- NoSQL Data Access API: connects to NoSQL key-value stores (eg: Redis), executes operations (eg: get) and retrieves results
- Web Security API: performs authentication and authorization on different combinations
- OAuth2 Client API: communicates with OAuth2 Providers (eg: Facebook) in order to retrieve remote resources owned by client
- HTTP Headers API: encapsulates HTTP Request/Response headers according to ISO standards and applies Cache/CORS validation when demanded
- Internationalization API: makes it possible for HTML views to be translated automatically to client's locale
First two are an absolute necessity, so they have been installed already! The rest, however, can either be bound manually or using the step-by-step configurer below.
Project Structure
Any project using this framework will use following file/folder structure:
- .htaccess: Apache2 configuration file redirecting all requests to index.php file, except those pointing to public, and sets development ENVIRONMENT to local.
- composer.json: framework or your project composer dependencies definitions
- configure.php: step-by-step console configurer adapting framework to your project needs
- index.php: bootstrap PHP file that makes framework sole handler of HTTP requests and errors/uncaught exceptions
- stderr.xml: configures STDERR MVC API to manage exception-response flow. Framework knows of following tags already:
- stdout.xml: configures STDOUT MVC API to manage request-response flow. Framework knows of following tags already:
- application: contains your non-static project files (php, html), with following files/folders inside:
- cacheables: contains \Lucinda\Headers\Cacheable implementations, detected based on headers tag @ stdout.xml, used to generate ETag/LastModified values for responses. Framework comes with following pre-installed:
- controllers: contains \Lucinda\STDOUT\Controller (or Lucinda\Framework\RestController, if your project is RESTful) implementations mapping requests to responses, detected based on routes tag @ stdout.xml, or \Lucinda\STDERR\Controller implementations mapping exceptions to responses, detected based on exceptions tag @ stderr.xml. Framework comes with following pre-installed:
- handlers: contains \SessionHandlerInterface implementations, detected based on session tag @ stdout.xml
- listeners: contains STDOUT MVC API event listeners, able to bind logic to application lifecycle events. Framework comes with following pre-installed (only ErrorListener ran by default):
- loggers: contains \Lucinda\Logging\Logger implementations, detected based on loggers tag @ stdout.xml, each able to log messages to a particular storage medium. Framework comes with following pre-installed:
- models: contains your project's PHP business logic. Framework comes with following pre-installed:
- renderers: contains \Lucinda\STDERR\ViewResolver implementations, detected based on resolvers tag @ stderr.xml, providing support for outputting normal responses in chosen display formats. Framework comes with following pre-installed:
- reporters: contains \Lucinda\STDERR\Reporter implementations, detected based on reporters tag @ stderr.xml, each able to report errors to a particular storage medium. Framework comes with following pre-installed:
- resolvers: contains \Lucinda\STDOUT\ViewResolver implementations, detected based on formats tag @ stdout.xml, providing support for outputting error responses in chosen display formats. Framework comes with following pre-installed:
- tags: contains View Language API tag libraries, useful in breaking up HTML templates into reusable parts that extend HTML standard
- views: contains View Language API templates (themselves to be broken into sub-templates or tags)
- compilations: contains View Language API compilations of templated views into PHP
- public: contains your static project files (images, js, css)
- vendor: contains APIs pulled based on composer.json above via composer update
To easily integrate APIs other than absolute minimal (STDOUT/STDERR MVC APIs), go to project root and run in console/terminal:
php configure.php project
A step-by-step installer will configure your project based on following options:
- isREST: whether your project is a RESTful web service API. Default: 0 (no)
- logging: whether your project will support logging (excluding errors). Default: 1 (yes)
- headers: whether your project will require validation by HTTP headers. Default: 1 (yes)
- caching: whether your project will be able to cache response via HTTP headers through HTTP caching validation. Default: 1 (yes)
- no_cache: whether or not HTTP caching should be disabled by default and allowed on a route basis only. Default: 0 (no)
- expiration: how many seconds you want response to be served from browser cache without any server round-trip. Default: 0
- cors: whether your project will be able to answer OPTIONS requests for CORS validation. Default: 0 (no)
- allow_credentials: whether or not credentials are allowed in CORS requests. Default: 1 (yes)
- max_age: duration in seconds CORS responses will be cached by client browser. Default: 0
- allowed_request_headers: (optional) request headers that are by default allowed in your site, separated by comma
- allowed_response_headers: (optional) response headers that are by default exposed by your site, separated by comma
- internationalization: whether your project is expected to be automatically displayed into multiple languages. Default: 0 (no)
- defaultLocale: default locale your site will be using, following iso language and country code standard. Default: en_US
- 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!
- sqlServer: whether your project will work with SQL databases. Default: 1 (yes)
- driver: the SQL vendor you will be using. Available options (choose index number):
Other popular vendors (MS SQL, PostgreSQL, Oracle) will be supported in the near future!
- host: ip address of server host. Default: 127.0.0.1 (localhost)
- port: (optional) server port. If not filled, default is used!
- user: user name to connect to server with
- password: user password to connect to server with
- schema: schema your app will be installed into
- nosqlServer: whether your project will work with key-value store NoSQL databases. Default: 0 (no)
- 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!
- host: (skipped if apc/apcu) ip address of server host. Default: 127.0.0.1 (localhost)
- port: (skipped if apc/apcu, optional otherwise) server port. If not filled, default is used!
- user: (skipped if not couchbase) user name to connect to server with
- password: (skipped if not couchbase) user password to connect to server with
- bucket: (skipped if not couchbase) bucket your app will be installed into
- bucket_password: (skipped if not couchbase, optional otherwise) password to connect to bucket with
- security: whether your project will have resources requiring authentication and authorization. Default: 0 (no)
- isCMS: whether your project is a CMS, requiring authentication and authorization for all resources except login. Default: 0 (no)
- 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
- 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!
- 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