Giandonato Inverso
311 lines
20 KiB
HTML
311 lines
20 KiB
HTML
<!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>PHP Qr Code Generator - Documentation</title>
|
||
|
||
<link href="assets/bootstrap.min.css" rel="stylesheet">
|
||
<link href="assets/style.css" rel="stylesheet">
|
||
<link href='http://fonts.googleapis.com/css?family=Lato:100,300,400,700,900,100italic,300italic,400italic,700italic' rel='stylesheet' type='text/css'>
|
||
|
||
<!-- HTML5 shim and Respond.js for IE8 support of HTML5 elements and media queries -->
|
||
<!-- WARNING: Respond.js doesn't work if you view the page via file:// -->
|
||
<!--[if lt IE 9]>
|
||
<script src="https://oss.maxcdn.com/html5shiv/3.7.2/html5shiv.min.js"></script>
|
||
<script src="https://oss.maxcdn.com/respond/1.4.2/respond.min.js"></script>
|
||
<![endif]-->
|
||
</head>
|
||
|
||
<body>
|
||
|
||
<!-- Left Panel Start -->
|
||
<div class="leftpanel">
|
||
|
||
<nav class="navbar navbar-default sidebar" role="navigation">
|
||
<div class="container-fluid">
|
||
<div class="navbar-header">
|
||
<button type="button" class="navbar-toggle" data-toggle="collapse" data-target="#bs-sidebar-navbar-collapse-1">
|
||
<span class="sr-only">Toggle navigation</span>
|
||
<span class="icon-bar"></span>
|
||
<span class="icon-bar"></span>
|
||
<span class="icon-bar"></span>
|
||
</button>
|
||
<a class="navbar-brand page-scroll" href="#header" style="margin-top: -50px">
|
||
<img src="assets/DynamicQRCode_Original.png" style="width: 200px; heigth: 63px">
|
||
</a>
|
||
</div>
|
||
<div class="collapse navbar-collapse" id="bs-sidebar-navbar-collapse-1">
|
||
<ul class="nav navbar-nav">
|
||
<li class="active"><a class="page-scroll" href="#header">Start</a></li>
|
||
<li><a class="page-scroll" href="#setup">Setup</a></li>
|
||
<li><a class="page-scroll" href="#upgrade">Upgrade</a></li>
|
||
<li><a class="page-scroll" href="#multi-account">Multi account</a></li>
|
||
<li><a class="page-scroll" href="#frontend">Frontend Files Structure</a></li>
|
||
<li><a class="page-scroll" href="#script">Script structure</a></li>
|
||
<li><a class="page-scroll" href="#dynamic-qrcode">Dynamic Qr code class</a></li>
|
||
<li><a class="page-scroll" href="#static-qrcode">Static Qr code class</a></li>
|
||
<li><a class="page-scroll" href="#dashboard">Dashboard</a></li>
|
||
<li><a class="page-scroll" href="#read">Read a Qr code</a></li>
|
||
</ul>
|
||
</div>
|
||
</div>
|
||
</nav>
|
||
|
||
</div>
|
||
<!-- Left Panel End -->
|
||
|
||
<!-- Main Panel Start -->
|
||
<div class="mainpanel">
|
||
|
||
<div class="title" id="header">
|
||
<h1>PHP Dynamic Qr code - v2.x</h1>
|
||
<small> Documentation - v2.x / Last Update: 16/10/2023</small>
|
||
<!--<h2 style="color: black">Technical documentation deprecated as the core of the project has been modified in version 2.0</h2>-->
|
||
</div>
|
||
|
||
<div class="wrapper">
|
||
<h2> About PHP Dynamic Qr code</h2>
|
||
<p><b>PHP Dynamic Qr code </b> is a script that allows the generation and saving of dynamic and static QR codes. It has clean, responsive and user-friendly design. It is Based on <a href="https://adminlte.io/" target="_blank">AdminLte </a> the <i>"Best open source admin dashboard & control panel theme. Built on top of Bootstrap" </i> and <a href="https://github.com/chetans9/core-php-admin-panel" target="_blank">Core PHP Admin Panel,</a> a simple Admin Pannel written in core PHP that contains an implementation of general features you might need in your website admin panel like: record management (CRUD), secure authentication, pagination, filters.<br><br>
|
||
N.B. A <strong>careful reading</strong> of this documentation is recommended to fully understand how the script works.
|
||
</p>
|
||
|
||
<h2> What is a dynamic qr code</h2>
|
||
<p><strong>A Dynamic QR code has a modifiable destination URL.</strong><br> A Short URL is placed into the QR code which then transparently re-directs the user to the intended destination. The destination of a dynamic QR code can be changed at any time and as often as you want – even if your marketing material has already been printed. This will save reprinting costs, effort and enable you to respond to any changes in the campaign as quickly as possible.</p>
|
||
|
||
<h2> What is a static qr code</h2>
|
||
<p><strong>A Static QR code has a fixed destination URL.</strong><br> The information encoded in <b>static QR codes are fixed</b>. The destination/data is stored directly in the QR Code graphic (hence QR codes are also getting larger and form a more complex pattern if there is more data to store). Therefore, the stored destination/data cannot be changed. Any typo in an already printed QR code cannot be changed, as with any other printed material. <strong>Through this script you can create 13 different types of static qr code.</strong></p>
|
||
|
||
<div id="setup">
|
||
<h2> Setup</h2>
|
||
<p>You can choose between local installation (recommended for development) and docker installation (recommended for general use)</p>
|
||
<p><u>Follow these steps to install the script locally:</u></p>
|
||
<ol><strong>
|
||
<li>Clone the project from github</li>
|
||
<li>Edit config/environment.php with your database credential</li>
|
||
<li>Launch install/setup.php file in your browser </li>
|
||
<p>The script checks the requirements, write permissions on the generated folders and creates a database with sample data</p>
|
||
<li>Finish</li>
|
||
<p>If all went well you will see a summary screen with a login button (username: superadmin, password: superadmin). Alternatively, you will get an error message</p>
|
||
</ol>
|
||
<p><u>Follow these steps to install the script with docker via docker compose (simplest method, recommended):</u></p>
|
||
<ol>
|
||
<li>Download docker-compose.yml file from github and edit if you want (recommended)</li>
|
||
<li>docker compose build --no-cache && docker compose up -d</li>
|
||
<li>Open your browser at http://localhost:80 and login with (username: superadmin, password: superadmin) </li>
|
||
<li>Finish</li>
|
||
</ol>
|
||
<p><u>Follow these steps to install the script with docker via locally build image:</u></p>
|
||
<ol>
|
||
<li>Clone the project from github</li>
|
||
<li>Clone the database project from github: https://github.com/giandonatoinverso/PHP-Dynamic-Qr-code-db</li>
|
||
<li>Build and run both docker image: docker buildx build -f Dockerfile</li>
|
||
<li>Open your browser at http://localhost:80 and login with (username: superadmin, password: superadmin) </li>
|
||
<li>Finish</li>
|
||
</ol>
|
||
</div>
|
||
|
||
<div id="upgrade">
|
||
<h2> Upgrade</h2>
|
||
<p>To upgrade the program from version 1.0 to version 2.x and maintain backward compatibility with the QR codes you have already created, files and users, you can follow these steps:</p>
|
||
<ol><strong>
|
||
<li>Clone the project from github</li>
|
||
<li>Edit config/environment.php with your database credential</li>
|
||
<li>Launch upgrade/upgrade.php file in your browser </li>
|
||
<p>The script makes the necessary changes in the database that adapt to the new source code.</p>
|
||
<li>Finish</li>
|
||
</ol>
|
||
</div>
|
||
|
||
<div id="multi-account">
|
||
<h2> Multi account</h2>
|
||
<p>Starting from version 2.x, the functionality that supports the creation and management of QR codes with the support of multiple accounts has been added</p>
|
||
<ol><strong>
|
||
<li>Superadmin accounts can manage all users, all qrcodes created</li>
|
||
<li>Admin accounts can only manage QR codes created by them and "universal" ones, i.e. not associated with any specific account</li>
|
||
</ol>
|
||
</div>
|
||
|
||
|
||
<div id="frontend">
|
||
<h2> Frontend Files Structure</h2><br>
|
||
<strong>a) CSS Files
|
||
<ul>
|
||
<li>
|
||
dist/css/adminlte.min.css Contains general css codes for admin panel
|
||
</li>
|
||
<li>
|
||
dist/css/alt folder Contains additional styles files
|
||
</li>
|
||
<li>
|
||
plugins/fontawesome-free/css/all.min.css Contains css of fontawesome
|
||
</li>
|
||
<li>
|
||
plugins/bootstrap-colorpicker/css/bootstrap-colorpicker.min.css Contains css of color picker input data
|
||
</li>
|
||
<li>
|
||
plugins/daterangepicker/daterangepicker.css Contains css of daterange input data
|
||
</li>
|
||
<li>
|
||
plugins/overlayScrollbars/css/OverlayScrollbars.css Contains css of the scrollbar relating to template customization (top right)
|
||
</li>
|
||
</ul><br>
|
||
|
||
<strong>b) JS Files
|
||
<ul>
|
||
<li>
|
||
dist/js/adminlte.js Contains general js codes for admin panel
|
||
</li>
|
||
<li>
|
||
dist/js/custom.js Contains custom js code for front-end
|
||
</li>
|
||
<li>
|
||
build/ folder Contains general dashboard script codes
|
||
</li>
|
||
</ul><br>
|
||
|
||
<strong>c) Plugins used in application
|
||
<ul>
|
||
<li>
|
||
<strong><a href="https://getbootstrap.com/" target="_blank">Bootstrap</a></strong> The world’s most popular front-end open source toolkit
|
||
</li>
|
||
<li>
|
||
<strong><a href="https://itsjavi.com/bootstrap-colorpicker/" target="_blank">Bootstrap colorpicker</a></strong> Bootstrap Colorpicker is a modular color picker plugin for Bootstrap 4
|
||
</li>
|
||
<li>
|
||
<strong><a href="https://www.chartjs.org/" target="_blank">Chart JS</a></strong> Simple yet flexible JavaScript charting for designers & developers
|
||
</li>
|
||
<li>
|
||
<strong><a href="https://www.daterangepicker.com/" target="_blank">Date Range Picker</a></strong> A JavaScript component for choosing date ranges, dates and times
|
||
</li>
|
||
<li>
|
||
<strong><a href="https://fontawesome.com/" target="_blank">Fontawesome</a></strong> The world's most popular and easiest to use icon set just got an upgrade
|
||
</li>
|
||
<li>
|
||
<strong><a href="https://jquery.com/" target="_blank">jQuery</a></strong> jQuery is a JavaScript library that greatly reduces the amount of code that you must write
|
||
</li>
|
||
<li>
|
||
<strong><a href="https://jqueryui.com/" target="_blank">jQueryUI</a></strong> jQuery UI is a curated set of user interface interactions, effects, widgets, and themes built on top of the jQuery JavaScript Library
|
||
</li>
|
||
<li>
|
||
<strong><a href="https://jqueryvalidation.org/" target="_blank">jQuery Validation</a></strong> This jQuery plugin makes simple clientside form validation easy
|
||
</li>
|
||
<li>
|
||
<strong><a href="https://momentjs.com/" target="_blank">Moment JS</a></strong> Moment will still create a moment global, which is useful to plugins and other
|
||
</li>
|
||
<li>
|
||
<strong><a href="https://kingsora.github.io/OverlayScrollbars" target="_blank">Overlay Scrollbars</a></strong> A JavaScript scrollbar plugin which hides native scrollbars and provides
|
||
custom styleable overlay scrollbars
|
||
</li>
|
||
</ul><br>
|
||
|
||
<strong>d) Open source libraries used
|
||
<ul>
|
||
<li>
|
||
<strong><a href="https://github.com/ThingEngineer/PHP-MySQLi-Database-Class" target="_blank">MysqliDb</a></strong> Simple MySQLi wrapper and object mapper with prepared statements
|
||
</li>
|
||
<li>
|
||
<strong><a href="https://github.com/pH-7/QRCode-Generator-PHP-Class" target="_blank">vCard Qr code</a></strong> This class allows to easily generate a simple QR code using vCard 4.0
|
||
</li>
|
||
<li>
|
||
<strong><a href="https://gist.github.com/jakebellacera/635416" target="_blank">PHP to ICS</a></strong> A convenient script to generate iCalendar (.ics) files on the fly in PHP
|
||
</li>
|
||
</ul><br>
|
||
</div>
|
||
|
||
<br>
|
||
|
||
<div id="script">
|
||
<h2> Script Structure</h2>
|
||
<ol>
|
||
<li>General</li>
|
||
<p>
|
||
All pages include the <b>config.php</b> file which in turn includes the <b>helpers.php</b> file and the <b>MysqliDb class</b> and the <b>auth_validation.php</b> file which takes care of verifying on each page that the user is logged in (read authentication types).
|
||
</p>
|
||
|
||
<p>As for the HTML structure, all pages start by including the <b>head.php</b> page which contains the entire head tag, the <b>navbar.php</b> page, the <b>sidebar.php</b> page.
|
||
There is a header with the page title and then the different main content for each page. Finally, each page includes the <b>footer.php</b> file with the required js scripts; some pages have <b>additional js scripts</b> needed
|
||
|
||
As specified at the beginning, the frontend part of this script is done with <b>AdminLTE</b> (Bootstrap). We therefore recommend reading the official documentation to fully understand the HTML structure.
|
||
</p>
|
||
|
||
|
||
<li>Qr code and Admin users</li>
|
||
|
||
<p>
|
||
<b>The dashboard page has a separate structure</b>, while the dynamic qr codes, static qr codes and users sections have a <b>very similar structure</b> to each other:
|
||
</p>
|
||
<ol>
|
||
<li><strong>dynamic_qrcodes.php</strong>, <strong>static_qrcodes.php</strong>, <strong>users.php</strong> allow you to view the relevant data</li>
|
||
<li><strong>dynamic_qrcode.php</strong>, <strong>static_qrcode.php</strong>, <strong>user.php</strong> allow you to add, modify and delete the relevant data</li>
|
||
</ol>
|
||
|
||
</ol>
|
||
</div>
|
||
|
||
<p><strong>This script is designed as OOP as possible. Therefore, all QR code handling operations are performed using classes and methods. There are 3 classes for 3 the three sections (dynamic qrcodes, static qrcodes, users) and dynamic qrcodes, static qrcodes share a single Qrcode class which contains some methods used by both classes</strong></p>
|
||
|
||
<div id="dynamic-qrcode">
|
||
<h2> Dynamic Qr code</h2><br>
|
||
<p>The physical creation of a dynamic qr code is managed by a free external provider https://api.qrserver.com/</p>
|
||
</div>
|
||
|
||
<div id="static-qrcode">
|
||
<h2> Static Qr code</h2><br>
|
||
<p>The physical creation of a static qr code is managed by a free external provider https://api.qrserver.com/ and previously is managed differently depending on the type</p>
|
||
</div>
|
||
|
||
<div id="dashboard">
|
||
<h2>Dashboard</h2>
|
||
<p>The dashboard is the main page of the script. In this section there is a counter of the total number of qr code in the database, and in particular also the number of dynamic and static ones. There is also a counter regarding the number of <strong>scans of the dynamic qr code</strong>.<br>
|
||
The script offers 2 examples of dynamic charts created with chart.js
|
||
The first shows a weekly report of the number of qr codes created (dynamic and static), the second graph offers an overview of the number of scans of dynamic qr codes.
|
||
</div>
|
||
|
||
<div id="read">
|
||
<h2>What happens when i scan a dynamic qr code?</h2>
|
||
<p>When a dynamic QR code is scanned, the read.php page opens by default which increases the scan counter and takes care of carrying out the appropriate redirect.
|
||
|
||
You can change the name of this page by remembering to change the constant defined in config.php
|
||
|
||
You can also customize the redirect page and increase the timer
|
||
</p>
|
||
</div>
|
||
|
||
<div id="extra">
|
||
<h2>EXTRA</h2>
|
||
<p>My script is in constant development and I hope to expand it from time to time with more and more useful features, so stay tuned for the updates.<br> With the first version, in the classes that realize the 2 types of qr code, an additional method not mentioned in the above documentation called <strong>addLogo()</strong> is included.
|
||
|
||
To add this functionality you need to delete the comment characters inside the class and add the input fields to the forms for the user to upload the logo.
|
||
|
||
However, this feature is not recommended as it can cause different QR code scanning errors depending on the scanner applications.
|
||
</p>
|
||
</div>
|
||
|
||
<div id="support">
|
||
<h2>Support</h2>
|
||
<div class="wrapper">
|
||
<div class="alert alert-success alert-dismissible" role="alert">
|
||
If you have any question please feel free to email me at <strong><a href="mailto:info@giandonatoinverso.it?Subject=Dynamic%20Qrcode" target="_top">info@giandonatoinverso.it</a></strong>
|
||
</div>
|
||
<p>Please don't forget to rate my script on GitHub.
|
||
<br>
|
||
<br>Thank You, <b><br><br> Giandonato Inverso</b></p>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<!-- Main Panel End -->
|
||
|
||
<!-- jQuery (necessary for Bootstrap's JavaScript plugins) -->
|
||
<script src="https://ajax.googleapis.com/ajax/libs/jquery/1.11.3/jquery.min.js"></script>
|
||
<!-- Include all compiled plugins (below), or include individual files as needed -->
|
||
|
||
<script src="assets/jquery.easing.min.js"></script>
|
||
<script src="assets/bootstrap.min.js"></script>
|
||
<script src="assets/run_prettify.js"></script>
|
||
<script src="assets/custom.js"></script>
|
||
|
||
</body>
|
||
</html> |