Installation
One of the important goals for the project are simple installation and upgrades. Let us know where you experience problems and we'll try to reduce the friction.
When you unpack the code into users folder, open it in your browser and installation wizard will walk you through the process.
Startup API uses PHP 5.4.0 or newer, after all it was released on 3/1/2012.
It also requires a few common extensions that might not be installed on your LAMP server. Click the links for installation instructions:
- php-mysqli for support of more performant and secure MySQL interface
- One of the encryption libraries for better security
- openssl standard openssl encryption library
- php-mcrypt older encryption library not included as of PHP 7.2.0
- libcurl / cURL for various network operations
- php-mbstring for international strings support (user names, for example)
Get the code from GitHub and place into the root directory of your website.
The following command places Startup API in the users folder (recommended default):
git clone git://github.com/StartupAPI/users.git users
If you already use Git for your code, you can use StartupAPI as a submodule:
git submodule add git://github.com/StartupAPI/users.git users
NOTE: A submodule can only be added from your git repository root directory. If your WEBROOT is not the root directory you can specify the applicable directory, e.g. www/users
If you do not use Git, you can just download latest package from package archive section.
If you don't have it yet, create MySQL database and get user credentials for it with following permissions: CREATE, ALTER, CREATE TEMPORARY TABLES, DELETE, DROP, INDEX, INSERT, SELECT, UPDATE.
mysql> CREATE SCHEMA IF NOT EXISTS example_schema;
mysql> CREATE USER schema_user@localhost IDENTIFIED BY 'password';
mysql> GRANT INSERT,UPDATE,DELETE,SELECT,CREATE,ALTER,DROP,CREATE TEMPORARY TABLES ON example_schema.* TO schema_user@localhost;
Some of these permissions (CREATE, ALTER, DROP, INDEX) are needed for creating database schema and can be removed after the installation step has been completed.
CREATE TEMPORARY TABLES is required for aggregatepoints.php script.
There is an issue #79 open for separating admin credentials (for schema manipulation) from application credentials. Why it is important to do so, see here: Why GRANT ALL is bad by Ronald Bradford.
Copy the sample configuration file from the installed users folder to the base directory of your website.
cp users/users_config.sample.php users_config.php
Open the users_config.php file with your favorite editor, and as minimum, seed the secret for cookie encryption and set your defined MySQL database credentials
<?php
/**
* You must fill it in with some random string
* this protects some of your user's data when sent over the network
* and must be different from other sites
*/
UserConfig::$SESSION_SECRET= '...type.some.random.characters.here...';
/**
* Database connectivity
*/
UserConfig::$mysql_db = '...database...';
UserConfig::$mysql_user = '...username...';
UserConfig::$mysql_password = '...password...';
#UserConfig::$mysql_host = 'localhost';
#UserConfig::$mysql_port = 3306;
#UserConfig::$mysql_socket = '/tmp/mysql.sock'; // in case you are using socket to connectRun make to generate database tables and other submodules and files required by the different parts of Startup API.
cd users
make
When completed you will see the following
...
[*** SUCCESS ***] Installation and upgrade of Startup API completed successfully
If you do not have make installed on your system, you can get the latest downloadable package (which contains all files including submodules) instead of checking code out of the repository.
For schema setup, just run
cd users
php dbupgrade.php
open http://yoursite/users/dbupgrade.php in your browser - this will create database schema (or update it if you already have older version).
Uncomment and configure API keys for more authentication modules for Facebook, Twitter, Google and etc.
You should now in a browser goto http://yourwebsite.com/users and complete the installation via the provided Wizard.
Start building your app by copying code from sample.php.
Basically, you'll need to include users.php at the top of the file
<?php
require_once( __DIR__ . '/users/users.php');StartupAPI uses Twig templating library internally and you're encouraged to use it for your application as well as it lets you separate logic from presentation and supports field escaping by default which is important for security.
Startup API already bundles Twig and initializes it upon load so all you need is to register your own templates with it.
<?php
require_once( __DIR__ . '/users/users.php');
StartupAPI::$template->getLoader()->addPath(__DIR__ . '/templates/', 'myapp');Twig uses a global template data object, you should start by getting values already initialized by StartupAPI and then build on it for your own pages. You can also reuse values already initialized which can save you some work.
// start with global template data needed for Startup API menus and stuff
$template_info = StartupAPI::getTemplateInfo();After you added your own fields to the $template_info object, you can just call Twig's display() method to render full template.
// render tempalte as HTML
StartupAPI::$template->display('@myapp/homepage.html.twig', $template_info);This will render a Twig template located in /templates/homepage.html.twig file in your project.
In order to use Statup API's menu system, including power strip with login/logout buttons, account management and etc. you can just extend base page template and fill content block with your page's content.
{% extends '@startupapi/page.html.twig' %}
{% block content %}
<section>
<h1>My page</h1>
<p>This is the content of my project</p>
</section>
{% endblock %}See page.html.twig template for other blocks to override and Twig's template documentation for syntax.
Startup API uses Bootstrap v3 CSS framework for styling (in default awesome template theme) and can be a good starting point for your application.
You can also configure different CSS themes provided by Bootswatch project. In users_config.php file, set UserConfig::$bootstrapTheme to one of the theme names to choose a different theme.
/**
* If specified, StartupAPI::head() will include this Twitter Bootstrap Theme instead of default one
*/
UserConfig::$bootstrapTheme = 'flatly';Enabling dev mode in users_config.php (don't use it in production) will add theme drop-down to the power strip so you can pick and choose themes on a current page and to help you make your HTML code compatible in case you'll want to switch a theme later.
UserConfig::$DEVMODE = TRUE;See theme example project that only has theme-specific configuration and showcases Bootswatch themes.
and then use either StartupAPI::getUser() static method to get a user object
/**
* Get User object or null if user is not logged in
*/
$current_user = StartupAPI::getUser();or if you want to protect the page from anonymous users, use StartupAPI::requireLogin() instead - this will automatically redirect to a login form and back to yout page after user successfully logged in or registered.
/**
* Get User object or redirect to login page if user is not logged in
*/
$current_user = StartupAPI::requireLogin();you can get numeric user ID to use in your data model by calling getID() method
/**
* Get user's unique ID
*/
$user_id = $current_user->getID();It is recommended to use Accounts instead of Users to associate your data. This way you'll be able to upgrade your initial single-user setup to multi-user accounts and work with subscription payments in the future without changing any of your code, just Startup API configuration. Each user gets one free account associated with them by default so it is the same as using users out of the box.
Similarly to Users, Accounts have unique integer IDs associated with them so you can display data associated with user's current account:
/**
* Get current Account object
*/
$current_account = $current_user->getCurrentAccount();
$current_account_id = $current_account->getID();or you can get a list of all user accounts:
<?php
/**
* Get all user accounts
*/
$user_accounts = $current_user->getAccounts();Sit back and relax Go implement your business logic now. You can call getID(), getName() and other methods on the user and account objects to utilize it in your code.
As usual, make a backup of the database to avoid loosing data in case of disasters.
Then just run make - it should grab the latest code and run database update scripts to bring schema up to date with the code.
make