Ferreteria: Difference between revisions

From Woozle Writes Code
Jump to navigation Jump to search
No edit summary
 
(18 intermediate revisions by 2 users not shown)
Line 1: Line 1:
[[Ferreteria]] is a web application framework I'm writing in PHP. It originally emerged from writing [[VbzCart]], when I realized a lot of the classes and techniques I'd created (starting with the database classes) could be used for other applications as well.
[[category:project]]
==About==
[[Ferreteria]] is a [[PHP]] web application framework. Its basic design does not rely on any special characteristics of the PHP language or environment and should be portable to other languages. The name literally means "hardware" in Spanish; I used it because I came across the word in a hardware store full of useful tools, which made it seem somehow appropriate as a name for a software toolkit, and also because I seem to be using the affix "ferret" in a lot of my software projects.


Because it does not use JavaScript (JS), it is very fast; response-times tend to be comparable to a "single-page app" framework written in JS, except that the initial load is as quick as subsequent reloads and all of the navigation links are bookmarkable.
Because it does not use JavaScript (JS) for core functionality, it is very fast; response-times tend to be comparable to a "single-page app" framework written in JS, except that the initial load is as quick as subsequent reloads and all of the navigation links are bookmarkable.
 
It originally emerged from writing [[VbzCart]], when I realized a lot of the classes and techniques I'd created (starting with the database classes) could be used for other applications as well.
{| class=wikitable
|-
| valign=top |
==Features==
==Features==
* '''User management'''
* '''User management'''
Line 14: Line 21:
** functions for specific tables can be built by descending from more general classes
** functions for specific tables can be built by descending from more general classes
** URL-linkable tables, records
** URL-linkable tables, records
==Applications==
===Premises===
Ferreteria applications I've written or am working on:
Every Ferreteria app will have ''some'' kind of on-server database, even if it's just a text file. (Currently only MySQL/MariaDB wrapper-classes are written.)
| valign=top |
==Pages==
* [[/install]]
* [[/errors]]: elaboration on various error messages
* [[/modules]]: available drop-in modules (includes table design pages)
* [[/archive]]: obsolete pages
 
For coding conventions used within Ferreteria, see [[conventions/coding]].
===versions===
Versions 1-3 need to be renamed to 0.1-0.3 because they're all pre-release. This has been done in the docs for v0.3, but some code referencing v3 may still exist.
* '''[[/v0.6|version 0.6]]''': yet more major refactoring, with some focus on CLI (Futilities)
* '''[[/v0.5|version 0.5]]''': major refactoring: namespaces, status objects, reworking of array objects, workspaces...
* '''[[/v0.4|version 0.4]]''': recordsets split into single-row records and multiple-row recordsets; using status objects more
* '''[[/v0.3|version 0.3]]''': had to temporarily abandon several weeks of work on this in January 2019
** [[/v0.3/class]]es
** [[/v0.3/fx]] (functions)
** [[/v0.3/usage/forms]]: early v3 usage documentation, probably needs update
* '''[[/v2|version 2]]''', 2017-2019: basically Ferreteria 1 with db.v2
** [[/v2/class]]: class structure
** [[/v2/usage]]: how to do things in Ferreteria, how the pieces work
* '''[[/v1|version 1]]''' never really had much documentation
** [[/v1/usage/forms]]
| valign=top |
 
==Apps==
* [[Greenmine]]
* [[Greenmine]]
** [[FinanceFerret]]
** [[FinanceFerret]]
Line 21: Line 53:
* [[VbzCart]]
* [[VbzCart]]
* [[Wikcess]]
* [[Wikcess]]
==Reference==
==Links==
* {{htyp}}: official documentation
===Official===
* {{l/htw|HyperAdmin}}: an early (2005) description of what eventually became Ferreteria's login system
* [https://gitlab.com/woozalia/ferreteria GitLab]: code repository
==Notes==
* [http://rm.vbz.net/projects/ferreteria Redmine @ vbz]: project tracker
(2020-04-22) With regard to the idea that [https://geometrian.com/programming/tutorials/write-games-not-engines/ it's better to set out to write an app than to write a framework], some background:
|}
 
I started writing Ferreteria before I knew that web app frameworks (WAFs) were a thing. I didn't even realize I was writing a framework; I just ended up realizing that a lot of the stuff I'd written could be reused.
 
Later on, after writing most of Ferreteria, I still didn't know that WAFs were a thing; all I knew about was CMSs that could be used as frameworks -- like WordPress, Drupal, and Joomla. I looked seriously at Drupal a couple of times, but there were bits of it I really didn't like, so I decided to stick with Ferreteria.
 
When I did find out about WAF, my impression was that they were all heavy on front-end scripting, possibly dependent on extra server processes (aside from basic stuff like Apache/Nginx and MySQL/Postfix), and generally kinda bloaty. Not really interested.
 
So now I'm at the point where I can see advantages to switching to a 3rd-party WAF -- although I still don't know of any PHP frameworks which fit the bill (no JS required, but handling front-end GUI stuff like logins and menu-navigation). They may exist, but finding that information seems to be a slow process. (There are non-PHP frameworks which look like they might, but that'll require learning a new language-environment, which increases the amount of time-investment needed in order to get anywhere. That's not a deal-breaker, but it does weigh against those options.)
 
What I'm thinking is that I'll go ahead and get Ferreteria where I think it needs to be in order to be useful and maintainable, then take a closer look at the field and see what else is available.
 
It may be that what anyone else has written will never work as well for my brain as something I've written -- but given that even what I've written often leaves me going WTF, I don't feel huge emotional investment in that idea. e.g. I used MediaWiki for lots of stuff for many years, and found much to complain about, but it was still very useable as a framework.
 
<blockquote>You can sit down and write a game without first writing an engine, and in fact this is very often the better approach...</blockquote>
Substitute "web app" for "game", and this is in fact what I set out to do; the engine (framework) just kinda happened by accident, as I found myself doing certain operations over and over again... and then started seeing patterns across different operations which could be generalized into a class hierarchy...
 
<blockquote>Most hobby developers who “finish” an “engine” that was designed and built in isolation (with the goal of having an engine, not a game, upon completion) can’t ever actually use it, and neither can anybody else. Since the project didn’t have any goals, any boundaries, or any tangible applications, it essentially attempted to solve every aspect of the chosen problem space and consequently failed miserably.</blockquote>
Trying to make the API too general, to cover cases that I ''might'' run into at some point but haven't actually encountered yet and may ''never'' encounter, was a mistake I made at first -- but now I'm trying to be much more rigorous about requiring not only usage-cases for every function, but also documentation of at least one example, in the comments, when it doesn't seem totally obvious how a function or class might be needed.
 
I'm kinda realizing in retrospect how much Ed at [[Carrier]] taught me about app design -- especially business app design, but this article makes me think that many of the principles apply to game app design as well.
# Have a clear idea in mind of what you want
# Spell out as much as possible the mechanics of how it will work
# Code from that spec.
 
I tend to be weak on step 2 because it's really time-consuming and means a longer gap between idea and something that does anything and gives you that necessary jolt of dopamine for wanting to keep going, but I tend to fall back on it when things get too complex to keep in my head. ...if I can even figure out how to document what I've got in my head (which has been a sticking point for this latest round of revisions).
 
(When I say "it's really time-consuming", of course i mean mainly in the short run -- in the long run it saves time, because better code that's easier to maintain.)

Latest revision as of 15:49, 21 January 2025

About

Ferreteria is a PHP web application framework. Its basic design does not rely on any special characteristics of the PHP language or environment and should be portable to other languages. The name literally means "hardware" in Spanish; I used it because I came across the word in a hardware store full of useful tools, which made it seem somehow appropriate as a name for a software toolkit, and also because I seem to be using the affix "ferret" in a lot of my software projects.

Because it does not use JavaScript (JS) for core functionality, it is very fast; response-times tend to be comparable to a "single-page app" framework written in JS, except that the initial load is as quick as subsequent reloads and all of the navigation links are bookmarkable.

It originally emerged from writing VbzCart, when I realized a lot of the classes and techniques I'd created (starting with the database classes) could be used for other applications as well.

Features

  • User management
    • log-in control: email-based account creation, password reset
    • user-group assignment, group-permissions assignment
  • State persistence via URL
    • The only cookie stored is a single "session" cookie, which usually just stores the minimum needed for session security.
      • Most app-state data is stored in the URL path, without even using the ?query part of the URL, for practical and aesthetic reasons.
  • Database wrappers
    • classes for different types of tables, records
    • classes for handling forms, controls, data fields
    • functions for specific tables can be built by descending from more general classes
    • URL-linkable tables, records

Premises

Every Ferreteria app will have some kind of on-server database, even if it's just a text file. (Currently only MySQL/MariaDB wrapper-classes are written.)

Pages

For coding conventions used within Ferreteria, see conventions/coding.

versions

Versions 1-3 need to be renamed to 0.1-0.3 because they're all pre-release. This has been done in the docs for v0.3, but some code referencing v3 may still exist.

  • version 0.6: yet more major refactoring, with some focus on CLI (Futilities)
  • version 0.5: major refactoring: namespaces, status objects, reworking of array objects, workspaces...
  • version 0.4: recordsets split into single-row records and multiple-row recordsets; using status objects more
  • version 0.3: had to temporarily abandon several weeks of work on this in January 2019
  • version 2, 2017-2019: basically Ferreteria 1 with db.v2
  • version 1 never really had much documentation

Apps

Links

Official

Retrieved from "https://wooz.dev/mw/index.php?title=Ferreteria&oldid=7190"