diff --git a/DEVELOPING.md b/DEVELOPING.md index 1323a30..bab26c8 100644 --- a/DEVELOPING.md +++ b/DEVELOPING.md @@ -1,146 +1,163 @@ # Boz PHP - Another PHP Framework ## Project structure * `load.php` - Should be unversioned (database credentials, `ROOT`, `ABSPATH` constants, etc.) * `load-post.php` - Can be versioned (roles, permissions, JavaScript and CSS files, etc.) ## Sample page Here an example of `index.php`: -``` +```php

``` Long story short: just put a `require 'load.php'` in top of your template to access the framework. ## Query Note that as default no database ### Query (declarative) -``` +```php query( "ALTER TABLE ADD COLUMN `hello` ..." ); ``` ### Select rows (full list) -``` +```php // results as a pure array $posts = query_results( "SELECT post_title FROM wp_post" ); if( $posts ) { json( $posts ); } ``` Note that `query_results()` is better over `query_generator()` if: * You need the full list (e.g. to count, to convert as JSON, etc.) * You want to read the list multiple times ### Select rows (generator) -``` +```php // generator of results $posts = query_generator( "SELECT post_title FROM wp_post" ); if( $posts->valid() ) { foreach( $posts as $post ) { echo $post->post_title; } } ``` Note that `query_generator()` is better over `query_results()` if: * You do not need the full list (but just one at time) * You do not need to read the list multiple times. ### Query builder (object-oriented) -``` +```php // get a pure array $posts = ( new Query() ) ->from( 'post' ) ->queryResults(); ``` -``` +```php // generator of results $posts = ( new Query() ) ->from( 'post' ) ->queryGenerator(); ``` -``` +```php $posts = ( new Query() ) ->from( 'post' ) ->whereStr( 'post_title', $title ) ->whereInt( 'post_author_id', $author ) ->quereSomethingIn( 'post_status', [ 'private', 'stub', 'deleted' ] ) // implicit join + condition ->from( 'comment' ) ->where( 'comment.user_ID = user.user_ID' ) // explicit JOIN ON ->joinOn( 'LEFT', 'user', 'user.user_ID', 'post.post_author_id' ) ->queryResults(); ``` ## Insert Declarative way: -``` +```php insert_row( 'post', [ new DBCol( 'post_ID', $id, 'd' ), new DBCol( 'post_title', $title, 's' ), new DBCol( 'post_creation_date', 'NOW()', '-' ), ] ); ``` Object-oriented way: -``` +```php ( new Query() ) ->from( 'post' ) ->insertRow( [ new DBCol( 'post_ID', $id, 'd' ), new DBCol( 'post_title', $title, 's' ), new DBCol( 'post_creation_date', 'NOW()', '-' ), ] ); ``` ## Database object mapping -``` +```php // declare a class class Post extends Queried { const T = 'post'; // table name // do something with the attributes (post_title) public function safePrintAmazingTitle() { _esc_html( "Post title: {$this->post_title}" ); } } // retrieve a Post objet (or null) $post = Post::factory() ->select( 'post_title' ) ->limit( 1 ) ->queryRow(); if( $post ) { $post->safePrintAmazingTitle(); } +``` + +## CSRF protection + +To both identify a form and secure it against [Cross-site request forgery](https://en.wikipedia.org/wiki/Cross-site_request_forgery) you can use `form_action()` and `is_action()`: + +```php + + +
+ + +
``` \ No newline at end of file diff --git a/README.md b/README.md index c6c7d60..4f85cba 100644 --- a/README.md +++ b/README.md @@ -1,129 +1,135 @@ # SucklessPHP - Another PHP framework that sucks less This framework is my laser cannon that I used to develope dozen of very-different Content Management Systems made from scratch. Note that I very often deprecate and kill stuff depending on how I feel in the morning. ## Benefits I can create a RDBMS CMS with these features: +* stateless * efficient (very tiny footprint) +* [CSRF](https://en.wikipedia.org/wiki/Cross-site_request_forgery)-safe * on demand resource loader (e.g. DB connection is instantiated only if you use it, etc.) * query builder * associative options * database table prefix -* login and user capabilities (WITHOUT requiring PHP sessions) +* login and user capabilities (WITHOUT the need of PHP sessions) * secure file uploads with MIME type checks etc. * multilanguage (using the widely used GNU Gettext native or high-level) ## Requirements Obviously a webserver with PHP and MySQL or MariaDB working. Personally I have a simple GLAMP machine (GNU/Linux + Apache + PHP + MySQL or MariaDB). Extra packages suggested: * `libmagic-dev` The `libmagic-dev` package is in the main Debian GNU/Linux repository and so I think it is in all other GNU/Linux distributions. It is needed only if you need to upload files. ## Simplest shared installation As a shared library: one can serve many sites with a simple `require`. Start cloning the source-code in a shared folder as `/usr/share`: sudo git clone https://github.com/valerio-bozzolan/suckless-php.git /usr/share/php/suckless-php That's it! Leave that folder as is, you don't have to touch it anymore. ## Use it Go to your website folder (e.g. `/var/www/blog`), and create your friendly config file. I use to call it `load.php` and please do so. Write in something as: ```php time; echo "If you see the datetime, the database works!"; ``` ## Database installation You can add support for user *autentication* / user *permissions* and *associative options* importing the database schema into your database. To do it you should have received a file called `example-schema.sql` in the `examples` framework folder. Import it into your database. Actually there are only two tables. ## Stuff in `load.php` Have to specify these: * `$username` (`string`) The database username. * `$password` (`string`) The password of the database username. * `$database` (`string`) The database name. * `$location` (`string`) The database location. * `$prefix` (`string`) The database table prefix. * `ABSPATH` (`string`) The absolute pathname of your site (`__DIR__` is your friend). No trailing slash. * `ROOT` (`string`) The absolute request pathname (something as `/blog` or simply an empty string). No trailing slash. Definibles (as (`type`) `default`): * `DEBUG` (`bool`) `false`: Enable verbose debugging. * `DEBUG_QUERIES` (`bool`) `false`: The queries are logged, and also printed when also `DEBUG`. * `PROTOCOL` (`string`): Default is the protocol of the request (`http://` / `https://`). It builds the `URL` constant. * `DOMAIN` (`string`): Default is your domain name. You can override it. It builds the `URL` constant. * `URL` (`string`): Default is `PROTOCOL . DOMAIN . ROOT`. * `REQUIRE_LOAD_POST` (`string|false`) `string`: As default it's `ABSPATH . '/load-post.php` and it's a file that describes your CMS. ## What you have then Well. I hope to auto-document it with inline comments. For now you can just see `functions.php` in the framework folder. ## Own functions / stuff It's normal to have your own custom configuration of this framework. So the `load-post.php` file is made for you. Create it and write in it what you want: ```php 'pdf', 'application/x-pdf' => 'pdf', 'application/x-bzpdf' => 'pdf', 'application/x-gzpdf' => 'pdf' ] ); // Custom menu tree declaration add_menu_entries( [ new MenuEntry( 'index', 'home.php', __("Home") ), new MenuEntry( 'services', 'services.php', __("Our services") ), new MenuEntry( 'contact', 'meet.php', __("Meet us"), 'services'), new MenuEntry( 'fsf', 'https://fsf.org/', __("Meet us in Colorado"), 'contact'), ] ); // Use of custom associative options // $visits = get_option('visits', 0); // set_option('visits', ++$visits); ``` +## Hacking + +See [DEVELOPING.md](./DEVELOPING.md). + ## License Copyright (c) 2015-2019 [Valerio Bozzolan](http://boz.reyboz.it/) This is a **Free** as in **Freedom** project. It comes with ABSOLUTELY NO WARRANTY. You are welcome to redistribute it under the terms of the **GNU General Public License v3+**.