firefly-php/README.html at master · georg94/firefly-php · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <meta http-equiv="X-UA-Compatible" content="IE=edge">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <title>Firefly-PHP Documentation</title>
    <style type="text/css">
        a {
          color:#000;
          font-weight:700;
          text-decoration:none;
        }

        a:hover {
          text-decoration: underline;
        }


    </style>
  </head>
  <body>
    <h1>Firefly-PHP Documentation</h1>
    <hr>
    <h2>About</h2>
    <pre>
      A simple and smallweight path routing framework to build any kind of web application. Its Plugin/Helper based so easy to enlarge functionality.
    </pre>
    <hr>
    <h2>Getting started</h2>
    <pre>
      1. Clone the current version of firefly-php from https://github.com/singhtreehouse/firefly-php.git .
      2. Change the <b>app/config.php</b> for your needs.
      3. Check out the example controller <b>app/controller/index/index.php</b>
      4. Check out the example plugin <b>app/plugins/frontend/frontend.php</b>
      5. Begin develop .) for further information check the following topics or mail me (singh@devilcode.org) .
    </pre>
    <hr>
    <h2>File-Structure</h2>
    <pre>
      This part contains a simple overview over our file structure. For further information just scroll down.

      <b>- public/</b>
      The public directory includes all your public direct accessable files. Its meant to be your document root.


      <b>- app/</b>
      The application path includes all business logic of your webapplication. Since <b>public/</b> is meant to be your
      document root , the <b>app/*</b> can't be called directly and ensures that you cant produce bugs/security flaws to
      single call files out of their context. The <b>app/</b> directory includes the following files[f]/directories[d]:

      [f] <b>bootstrap.php</b>
      [f] <b>config.php</b>
      [f] <b>models.php</b>
      [f] <b>router.php</b>
      [d] <b>controller/</b>
      [d] <b>helper/</b>
      [f] <b>helper/instance.php</b>
      [d] <b>plugins/</b>
      [d] <b>storage/</b>


      <b>- app/controller/</b>
      The controller directory basicly includes your business logic , build up in a structure like:
      <b>app/controller/{YOUR_CONTROLLER_NAME}/{YOUR_CONTROLLER_NAME}.php</b>


      <b>- app/helper/</b>
      The helper directory basicly includes all your snippets you use on multiple controller/plugins and
      the <b>instance.php</b> wich is needed to use your helper.
      The structure is build up like:
      <b>app/helper/instance.php</b>
      <b>app/helper/{YOUR_HELPER_NAME}/{YOUR_HELPER_NAME}.php</b>


      <b>- app/plugins/</b>
      The plugins directory basicly includes your frontend plugin logic , build up in a structure like:
      <b>app/plugins/{YOUR_PLUGIN_NAME}/{YOUR_PLUGIN_NAME}.php</b>


      <b>- app/storage/</b>
      The storage directory is compareable to the <b>upload/</b> or <b>data/</b> directory. Its a storage directory for
      any type of ressources. Since it is outside the document root you can place even sensitive files into
      it.

    </pre>
    <hr>
    <h2>config.php</h2>
    <pre>
      The <b>config.php</b> contains all basic needed system configurations. This includes the base_href ,directory
      paths, database login data , etc.

      If you want to add other data into configuration simply place a call like the following pattern into your <b>config.php</b>

      <b>config::set("{name}","{value}");</b>

      Since the config is handled within a static class its global accessable and you can get all config data just using
      the following pattern:

      <b>config::get("{name}");</b>

      PS: If you enable the debug mode (<b>conf::set("debug",true)</b>) the logger will log <b>info</b> and <b>warnings</b> too.
          On default (debug = false) it will only log errors.

    </pre>
    <hr>
    <h2>bootstrap php</h2>
    <pre>

      The <b>bootstrap.php</b> contains some calls to setup the system and the registration of callable paths.

      This includes the following:

        - Startup Session              // can be removed if unnecessary
        - Setup Database Connection    // can be removed if not database usage needed
        - Init params class/modell     // system requirement, further explaination at section <b>models.php</b>
        - Register callable routes     // system requirement, further explaination at section <b>models.php</b>
        - Get the actual called route  // system requirement, further explaination at section <b>models.php</b>
        - Init Logger                  // system requirement, further explaination at section <b>models.php</b>

      If you need any preprocessing before the framework handles your call via plugin/controller , you can place
      it at the end of bootstrap.php. You should be able to call all helpers and access needed paths but are still
      before the execution of your business logic.

    </pre>
    <hr>
    <h2>models.php</h2>
    <pre>
        This file contains system required models/classes. I will explain them one for one in the following:

        <b>conf</b>

          The configuration model/class simply is a static class to be filled with global accessable data.
          It contains two methods, a getter and a setter. Since the class is build up static all calls
          will access the same object.

          The calls are simple as following:

          <b>Setter</b>
            <b>conf::set("{name}","{value}")</b>

          <b>Getter</b>
            <b>conf::get("{name}")</b>


        <b>params</b>

          The params model/class is build for a better input parameter usage. It allows you to access
          $_REQUEST , $_GET , $_POST via a simple call, and implements some santitations. It is inited
          inside the bootstrap.php. The usage is simple as following:

          <b>params::get("{name}")</b>                         // returns <b>$_REQUEST["{name}"]</b> or false
          <b>params::get("{name}","{type}")</b>                // returns <b>$_{type}["{name}"]</b> or false. Allowed types are <b>get</b> and <b>post</b>
          <b>params::get("{name}","{type}","{sanitation}")</b> // returns <b>$_{type}["{name}"]</b> after using <b>{santitation}</b> or false.


        <b>depends</b>

          The depends model/class is used for dependency management. This means if you are coding a <b>controller</b>, <b>plugin</b>
          or <b>helper</b> wich has a dependency to another of this, or simply makes no sense without one of those specific, you should
          add a dependency into your file. This is really simple. Just add at the top of your file a call like the following pattern.

          <b>depends::on(array("{type}:{name}"))</b> // Example depends::on{array("helper:paths")}

          Allowed Types are as following : <b>helper</b> , <b>controller</b> , <b>plugin</b>

          When the file gets required it will auto check if the dependency is given, if not it will log down an error and stop the
          process informing you about the missing dependency. Its important to conscientious add those to hav a valid and consistent
          development.


        <b>route</b>

          The route model/class is static and used ro register callable routes same as the system uses it to find out wich
          <b>controller</b>/<b>plugin</b> to load at a call. The call to get the actual route is inside the bootstrap.php
          below the <b>route::add</b> calls. This is important! Dont place <b>route::add</b> calls below the <b>route::getRoute</b>
          or they gonne be ignored.

          An simple example for an <b>route::add</b> call looks like following:

          <b>route::add(array("path"       => "test",
                           "controller" => "foo",
                           "plugin"     => "bar"));</b>

          To explain what you just did by registering this path.

          If a user calls <b>yourdomain.tld/test.html</b> , in wich <b>"test"</b> is the just registered path, the system will init
          the <b>plugin</b> <b>"bar"</b> givin it a new instancen of <b>controller</b> <b>"foo"</b>. Like this you register all
          your callable paths.

          A path can be displayd as too types , shown as following:
            - yourdomain.tld/test.html
            - yourdomain.tld/test/

          We decided to hav this handling to easy allow writing website-like applications same as f.e. REST-Apis.


          <b>Important!</b> - To catch/register the calls on <b>yourdomain.tld/</b> , so the <b>index</b> calls you need to register
          the <b>"index"</b> path. The system will auto-use the index path on docroot calls without further path params.


        <b>log</b>

          The log model/class is a simple logger class. On default it only logs errors, bug if you change the config flag <b>"debug"</b> on <b>"true"</b>
          it will log <b>info</b> and <b>warning</b> too .It contains 3 public methods to be called. These are:

          <b>log::info("{msg}")</b>         // To log simple informations , gud for debugging
          <b>log::warning("{msg}")</b>      // To log semi critical informations
          <b>log::error("{msg}")</b>        // To log critical errors, these will be loged even if conf-debug = false;


    </pre>
    <hr>
    <h2>router.php</h2>
    <pre>
      The router.php basicly is the core class of our system. It will be inited inside the <b>public/index.php</b>. It basicly contains
      the <b>bootstrap.php</b> call and initiates the <b>controller</b> and <b>plugin</b> that are needed for the called path. On
      call it generates a new instance of the registered <b>plugin</b> and gives it a new instance of the registered <b>controller</b>
      as __construct() param.
    </pre>
    <hr>
    <h2>instance.php</h2>
    <pre>
        The instance file includes a static class to get instances of your helpers. Its meant as basic for the helpers. It consists
        of two public callable methods:

        <b>helper::getInstance("{helper_to_call}")</b>        //returns a instance of <b>{helper_to_call}</b> wich will be cached and redelivered on same call
        <b>helper::getSingleInstance("{helper_to_call}")</b>  //returns a non-cached instance of <b>{helper_to_call}</b> that can be used in its own context.
    </pre>
    <hr>
    <h2>Plugins</h2>
    <pre>
      Plugins , or better said frontend plugins are meant to decide what output handling should be used on the data that your <b>controller</b> provides.
      It will be inited inside the router and presented to the <b>controller</b> as __construct() param. You can change its build-up free since the
      methods just must be standardized to be usefull for all <b>controllers</b>.


      To create a new plugin you hav to create it like the following explaination.

      In our example we gonne create the plugin <b>"frontend"</b>.

      1. Create the plugin directory
         - <b>app/plugins/frontend/</b>

      2. Place the controller PHP-file inside the directory with the same name
         - <b>app/plugins/frontend/frontend.php</b>

      3. Create a class inside the file you just created at 2. and fill it with a class
         that has the same name like your plugin , in this example
         - <b>class frontend {.....}</b>


      Now you just hav to register the <b>plugin</b> inside the bootstrap.php onto the path you wanne use it. So you simply can write f.e
      a plugin for. Some simple examples:

        - <b>frontend</b>    //basic html output
        - <b>api</b>         //REST api or others
        - <b>admin</b>       //backend that checks login state inside the plugin

    </pre>
    <hr>
    <h2>Controller</h2>
    <pre>
      The controller contains your main business logic. You can build it up completly free, besides the fact you need a __construct()
      method that inits the processing including it must accept <b>plugin</b>-instance as __construct param.

      To create a new controller you hav to create it like the following explaination.

      In our example we gonne create the controller <b>"index"</b>.

      1. Create the controller directory
         - <b>app/controller/index/</b>

      2. Place the controller PHP-file inside the directory with the same name
         - <b>app/controller/index/index.php</b>

      3. Create a class inside the file you just created at 2. and fill it with a class
         that has the same name like your controller , in this example
         - <b>class index {.....}</b>

      4. Make the __construct function of the class you just created at 3. accept an
         object/instance of the registerd <b>plugin</b>.

      In case you have a plugin that needs no further controller code, just create an empty controller that only handles the plugin basic
      output calls and register it to the path you.

    </pre>
    <hr>
    <h2>Helper</h2>
    <pre>
      The helpers are meant to contain code that is used on multiple places. Like in multiple controllers , multiple plugins or simply
      other helpers.

      To call a helper you got two different public methods given by <b>instance.php</b>

      1. <b>helper::getInstance("{name}");</b>
        - This will return an instance of the helper {name}. If the helper allready got called once, it will return a static cached object.
          This is usefull if you dont need a single instance for every call , or even if you need especially the same object again like
          a database class including the connection.

      2. <b>helper::getSingleInstance("{name}");</b>
        - This will return an instance of the helper {name}. The difference to helper::getInstance("{name}") simply is that you will recieve
          a new instance of the helper {"name"} instead of a cached one.


      To create a new helper you hav to create it like the following explaination.

      In our example we gonne create the helper <b>"upload"</b>.

      1. Create the helper directory
         - <b>app/helper/upload/</b>

      2. Place the controller PHP-file inside the directory with the same name
         - <b>app/helper/upload/upload.php</b>

      3. Create a class inside the file you just created at 2. and fill it with a class
         that has the same name like your helper , in this example
         - <b>class upload {.....}</b>


      <b>System basic helpers</b>


        <b>paths</b>

          The Paths helper is a basic system helper (means its shipped with the basic version of firefly-php) and its required for the system to work.
          it's usage is quite simple and really usefull for every development with firefly-php. Since we hav registered all system paths inside the
          <b>config.php</b> the paths helper provides a simple method of getting those paths.

          To get a path via the paths helper use the following pattern:
          - <b>helper::getInstance("paths")->get("{pathname}")</b>     // for example helper::getInstance("paths")->("storage")

          All paths you add inside the config.php using the same naming pattern like the system basic paths can be looked up via the
          paths helper.

          <b>Important!</b> - This helper is system required, if you remove it all hell breaks loose:


        <b>database</b>

          The database helper is a basic system helper (means its shipped with the basic version of firefly-php). It uses the database params you
          set inside the <b>config.php</b> to create a database connection (connection build up call is placed inside <b>bootstrap.php</b>).

          It contains 5 public methods
            - <b>connect()</b>               // Builds up a database connection using the db credentials set at <b>config.php</b> / is called default in bootstrap.php
                                      // using a static/cached object so you can refer to the same database connection at the full project source.
            - <b>query()</b>                 // Used to set up a mysql qry, it accepts 2 params - for more information read the database helper or simply ask me.
            - <b>fetch()</b>                 // Fetches the ressource returned by query() and returns an array
            - <b>getInsertId()</b>           // Returns the last id created by inserting data via the connection used by that database object
            - <b>disconnect()</b>            // Disconnect the connection of this database object


        <b>dbMapper</b>

          The database helper is a basic system helper (means its shipped with the basic version of firefly-php).
          It is meant for a better structured database usage. The followin explaination should show its usecase.


          The dbMapper gets called like every other helper. It provides one public function to use - <b>"get("{param}")"</b>. The function expects one string as parameter.
          The thought behind this is that you never need all database depending functions at once. You can split them by tables / context. So what this helper
          should do is deliver a instance of the <b>{name}Mapper</b> class inside <b>app/helper/dbMapper/tables/</b> directory. In the followin example we assume the existenz
          of the <b>"showsMapper"</b> inside the <b>tables/</b> directory.

          <b>helper::getInstance("dbMapper")->get("shows");</b>

          Now you can use the <b>showsMapper</b> instance to call all methods that include <b>shows</b> regarding functions.

          It's not forced to use this structure but its highly recommended due its efficiency plus (loading only ressources that are needed).

          To create a new Mapper use this instructions:

            1. Create a file inside the subdirectory <b>tables/</b>
              - <b>app/helper/dbMapper/tables/{name}Mapper.php</b>

            2. Create a class inside the in 1. created file wich has the
            same naming plus the string <b>"Mapper"</b>
              - <b>class {name}Mapper { .... }</b>        //for example: class showsMapper { .... }


    </pre>
  </body>
</html>