documentation/Fannie/developer/framework.html
<html>
<head>
<title>Framework</title>
</head>
<body>
<div style="text-align:center;margin-bottom:10px;font-size:80%;">
updated as of: March 30, 2015<br />
last author: Andy Theuninck
</div>
<div style="border: solid 1px black; font-size: 115%; padding: 1em;">
The latest documentation can be found on the <a href="https://github.com/CORE-POS/IS4C/wiki/Fannie-Framework-%26-Rules">Project Wiki</a>.
The information below may be out of date.
</div>
A framework needs some rules. I hate rules, so let's keep this short. I think we can share code if everyone can live with just two requirements.
<h3>One configuration</h3>
Let's all agree on one configuration file. I say it should be config.php and it should live at the root of fannie. The upside is every script needs just one relative include; variables in the config then fill in the rest of what you need. This lets fannie sit in subdirectories and lets any given tool/report find the top of fannie, regardless of whose store it's running at.
<h3>Database Best Practices</h3>
This is the hard part. Ideally, we'd all keep the same schema. With a little caution, I think we can at least have scripts that degrade gracefully when the underlying structure changes. These are not meant as permanent solutions; there practices should merely streamline schema changes and make them less disruptive. Ideas:
<ul>
<li>Grab row values by column name instead of numeric index. As long as the column exists, you'll get the right value, regardless of actual layout</li>
<li>Use the SQLManager class instead of database-specific functions (e.g., mysqli_connect). I know most people are using MySQL, but I don't see any downside to keeping the system fairly open. If someone wants to run IS4C on top of Postgres, it's a much easier port down the line. There are also a couple bits of handy functionality:
<li>Use prepared statements for any query involving a variable. The only exception is with code-generators that create snippets of SQL at runtime such as DTransactionsModel::selectDlog (calculate appropriate archive table name) or SQLManager::now (get database-specific datetime function). Anything the database considers data and can be substituted using placeholders and prepared statements should use placeholders and prepared statements. Question mark placeholders are preferred.</li>
<li>Use the <a href="db-alteration.html">BasicModel</a> classes where feasible. In particular in the case of INSERTs and UPDATEs models will cope with missing or extra columns without crashing. For simple queries models may lead to shorter code compared to manual prepared statements.
<li>Put CREATE statements in install.php when you need new tables. This makes it easy for other developers (and regular users) to add the tables your script needs. Don't drop and recreate tables that already exist; deleting someone else's data is impolite.</li>
<li>Publish schema updates via the <a href="db-alteration.html">provided system</a>. Before adding a column to a table and committing the change, ensure that queries involving the table will not break if the new column is missing. Again models can help with INSERTs and UPDATEs. If the column has a default value, which is usually a good idea, models can also help smooth over SELECTs with and without the column. If models do not fit the situation, SQLManager::tableDefinition will provide a list of columns that currently exist in a given table.</li>
</body>
</html>