simbiat/array2table

Library to convert arrays to table.

2.0.13+20240529 2024-05-29 08:19 UTC

Requires

• php: ^8.3
• simbiat/arrayhelpers: ^2.4.6

Suggests

• simbiat/cute-bytes: Allows to present bytes in human-readable format
• simbiat/http20: Provides 'pretty' function for pretty URLs
• simbiat/sand-clock: Collection of functions for presenting time-related objects

AGPL-3.0-or-later

• Dmitry Kustov

• php
• array
• converter
• table

README

Split data types into separate classes As result you can generate respective HTML elements from the respective classes directly, if required Sanitize flag is now per type Counts are now static in each respective class, and will increase with each successful generation Removed classes from the elements, since IDs will are enough (can be matched by wildcards) $dateformat moved to Types\Date class as $format and is now a public static string Date/time formatting with SandClock is done only if field is not editable and $sandClock attribute of the respective class is true Seconds now support all the SandClock attributes for seconds (as public static attributes) Seconds also now have a pattern for input field Bytes and Seconds now expect the CuteBytes and SandClock libraries to be present. If you do not want to use them - update respective flags in Type class URL now supports whitespace setting for PrettyURL. URLs are always sanitized Email and URL will throw an error if not a valid email/URL and not an empty string is provided, instead of creating a span

This library is used for creating HTML tables using data provided to it in an array. When will you want to use it? I believe, there are 2 use-cases:

• You are presenting a lot of homogeneous data from your database
• You are creating some relatively simple form (like user settings) and do not want that much customization for it

Yes, this library can be used for creating forms, that you will be able to process further, once they are submitted. And the unique feature here is that form elements will not be just text-fields: library supports checkboxes, date/time fields, colors, files, .etc. Each element will be created with the minimum required attributes, with automatically generated IDs and classes (for CSS customization or JavaScript interactivity, if required).

Note, that it is discouraged to use this library, if you already have a template engine (like Twig) in your project, since it will probably be more efficient and secure, especially when dealing with HTML inside the fields. Use of this library may make sense if you do not have anything generating actual web pages, and you want to generate some sort of report based on the output of a function.

• Data Types
• Settings

How to use

The best way to understand what you will be getting is a live example, so check out sample.html somewhere near this README. There you will find 3 tables, that were generated using following code:

echo (new \Simbiat\ArrayToTable\Generator)->setIdPrefix('sem_edit')->setCaption('Semantic, editable')->setFooter(['#func_sum','',''])->setCheckbox(true)->setChecked(true)->setEditable(true)->setTypes(['number','string',['text','password','tel','date', 'time', 'datetime', 'seconds', 'bytes', 'price', 'checkbox', 'email', 'url', 'html', 'img', 'color']])->generate(
    [
            ['Points'=>'1','Field'=>'Login','Value'=>'Simbiat'],
            ['1','Password','Simbiat'],
            ['1','Telephone','[phone]'],
            ['1','Date of birth','12-05-1989'],
            ['1','Current time',time(),],
            ['1','Last login',time(),],
            ['1','Seconds','123456',],
            ['1','Image size','1234567',],
            ['1','Salary','123456',],
            ['1','Are you a robot?','No',],
            ['1','Email','[e-mail]',],
            ['1','Website','https://www.simbiat.dev',],
            ['1','Signature','<a href="https://www.simbiat.dev">Awesome website</a>'],
            ['1','Avatar','https://media.kitsu.io/users/avatars/41172/large.jpg'],
            ['1','Favorite color','006E72'],
    ]
);

echo (new \Simbiat\ArrayToTable\Generator)->setIdPrefix('sem_nonedit')->setCaption('Semantic, non-editable')->setFooter(['#func_sum','',''])->setCheckbox(true)->setChecked(true)->setEditable(false)->setTypes(['number','string',['text','password','tel','date', 'time', 'datetime', 'seconds', 'bytes', 'price', 'checkbox', 'email', 'url', 'html', 'img', 'color']])->generate(
    [
            ['Points'=>'1','Field'=>'Login','Value'=>'Simbiat'],
            ['1','Password','Simbiat'],
            ['1','Telephone','[phone]'],
            ['1','Date of birth','12-05-1989'],
            ['1','Current time',time(),],
            ['1','Last login',time(),],
            ['1','Seconds','123456',],
            ['1','Image size','1234567',],
            ['1','Salary','123456',],
            ['1','Are you a robot?','No',],
            ['1','Email','[e-mail]',],
            ['1','Website','https://www.simbiat.dev',],
            ['1','Signature','<a href="https://www.simbiat.dev">Awesome website</a>'],
            ['1','Avatar','https://media.kitsu.io/users/avatars/41172/large.jpg'],
            ['1','Favorite color','006E72'],
    ]
);

echo (new \Simbiat\ArrayToTable\Generator)->setIdPrefix('nonsem_nonedit')->setCaption('Non-semantic, non-editable')->setSemantic(false)->setStyling(true)->setFooter(['#func_sum','',''])->setCheckbox(true)->setChecked(true)->setEditable(false)->setTypes(['number','string',['text','password','tel','date', 'time', 'datetime', 'seconds', 'bytes', 'price', 'checkbox', 'email', 'url', 'html', 'img', 'color']])->generate(
    [
            ['Points'=>'1','Field'=>'Login','Value'=>'Simbiat'],
            ['1','Password','Simbiat'],
            ['1','Telephone','[phone]'],
            ['1','Date of birth','12-05-1989'],
            ['1','Current time',time(),],
            ['1','Last login',time(),],
            ['1','Seconds','123456',],
            ['1','Image size','1234567',],
            ['1','Salary','123456',],
            ['1','Are you a robot?','No',],
            ['1','Email','[e-mail]',],
            ['1','Website','https://www.simbiat.dev',],
            ['1','Signature','<a href="https://www.simbiat.dev">Awesome website</a>'],
            ['1','Avatar','https://media.kitsu.io/users/avatars/41172/large.jpg'],
            ['1','Favorite color','006E72'],
    ]
);

Here's what the code does:

1. Create new object with (new \Simbiat\array2table). Obviously load the library before that.
2. Optionally set a prefix for elements' IDs and Classes with setIdPrefix('prefix'). Very useful, in case you will have multiple tables like that on one page, like sample.html does.
3. Optionally set caption for the table with setCaption('caption'). If this is set a <caption></caption> will be added to the table if it's semantic or respective <div></div> if it's not. Basically, this is a name of the table.
4. In case of non-semantic tables we have setSemantic(false). This forces use of <div></div> elements instead if regular (semantic) table elements (table, td, tr, th, etc.). When creating actual tables, it is recommended to use semantic approach (thus default is true), but in some cases you may want to have <div></div>.
5. Optionally enable basic styling for <div></div> elements for non-semantic approach with setStyling(true). This will add inline style attributes to make non-semantic table look more like its semantic counterpart. Styling is based on WebKit stylesheet at the time of writing.
6. Optionally set footer with setFooter(['','','']). If this is set <footer></footer> will be added to the table if it's semantic or respective <div></div> if it's not. This is a row that will appear at the bottom of the table. If set, its length will be checked against the number of columns the data have and if different - throw an exception. footer can be used to repeate header with setFooterHeader(true). In case of sample.html we also use #func_sum to calculate total (sum) of the values in respective column.
7. Optionally set currency for currency values with setCurrencyCode('USD '). Adding space at the end of the value will place the currency before the values. Default is '', that empty string.
8. Optionally set precision for currency values with setCurrencyPrecision(2). This determines number of digits after dot. Default is 2.
9. Optionally set initial format used by currency values with setCurrencyFraction(true). If true converter will expect values to be "fractions", like cents for USD, thus will consider the last 2 digits of a value as cents and put them after the dot. If false - will expect a float and/or convert to it.
10. Optionally add checkbox for each lie with setCheckbox(true). This may be useful when you want to allow user to remove some entries, for example. Set is as checked with setChecked(true).
11. Optionally make the values of the table editable with setEditable(true). This will replace values with appropriate <input> elements.
12. Optionally adjust size of <textarea> elements with setTextareaSetting('cols', '20')->setTextareaSetting('rows', '5').
13. Set values types with setTypes(['number','string',['text','password','tel','date', 'time', 'datetime', 'seconds', 'bytes', 'price', 'checkbox', 'email', 'url', 'html', 'img', 'color']]). In the example 2 first columns (array elements) have one type for all values in them. Both of them are not, actually, a supported type from the list, thus they will turn into regular <span></span> elements. The 3rd column uses an array of types with separate type for each row. It's not required to have different types for each: this is done only for the sample purpose to showcase all of currently supported types. It is required to have the same number of types as you have actual data rows or an exception will be thrown.
14. Actually generate the table with

generate(
    [
            ['Points'=>'1','Field'=>'Login','Value'=>'Simbiat'],
            ['1','Password','Simbiat'],
            ['1','Telephone','[phone]'],
            ['1','Date of birth','12-05-1989'],
            ['1','Current time',time(),],
            ['1','Last login',time(),],
            ['1','Seconds','123456',],
            ['1','Image size','1234567',],
            ['1','Salary','123456',],
            ['1','Are you a robot?','No',],
            ['1','Email','[e-mail]',],
            ['1','Website','https://www.simbiat.dev',],
            ['1','Signature','<a href="https://www.simbiat.dev">Awesome website</a>'],
            ['1','Avatar','https://media.kitsu.io/users/avatars/41172/large.jpg'],
            ['1','Favorite color','006E72'],
    ]

Each "inner" array in "outer" array represents a row, while each element in "inner" arrays - respective column. In sample 1st row is using an associative array for optional header value (creates <header></header>). Alternatively setHeader([]) can be used to the same effect.

Data types

Settings