Τεκμηρίωση PrizeX

Τι είναι το PrizeX

Το PrizeX είναι μια πλατφόρμα βραβείων, gaming και marketplace χτισμένη σε PHP: δημοπρασίες, λαχεία, mystery box, μια συστάδα arcade παιχνιδιών, ένα κατάστημα e-commerce πολλαπλών πωλητών και μια οικονομία πορτοφολιού/νομισμάτων — όλα σε μία αυτοφιλοξενούμενη εφαρμογή. Διατίθεται με αρχιτεκτονική πρόσθετων/θεμάτων, πίνακα διαχείρισης και 38 πρόσθετα πυλών πληρωμών που καλύπτουν κάρτες, ψηφιακά πορτοφόλια, crypto και τοπικούς επεξεργαστές πληρωμών, καθώς και 3 χειροκίνητες μεθόδους πληρωμής που έρχονται έτοιμες από τον πυρήνα.

Δεν υπάρχει εγκλωβισμός σε SaaS: το εγκαθιστάτε στο δικό σας hosting, η βάση δεδομένων σάς ανήκει και η άδεια σάς δίνει ενημερώσεις εφ' όρου ζωής. Κάθε κάθετη ενότητα (δημοπρασίες, λαχεία, mystery box, παιχνίδια, κατάστημα) ενεργοποιείται ή απενεργοποιείται ανεξάρτητα από τον πίνακα διαχείρισης — μια νέα εγκατάσταση μπορεί να λειτουργήσει ως προϊόν μίας μόνο κατηγορίας ή ως πλήρης σουίτα.

Σε τι τρέχει

Το PrizeX τρέχει σε συνηθισμένο κοινόχρηστο hosting ή σε VPS — δεν χρειάζεται καμία ιδιαίτερη ρύθμιση διακομιστή, πέρα από έναν διακομιστή web με δυνατότητα rewrite.

* Αρκετά αρχεία μέσα στο database/migrations/ χρησιμοποιούν την επέκταση ADD COLUMN IF NOT EXISTS, που υπάρχει μόνο στη MariaDB. Η απλή MySQL 8.0/8.4 την απορρίπτει — χρησιμοποιήστε MariaDB για τη βάση δεδομένων, τόσο στην ανάπτυξη όσο και στην παραγωγή.

Πώς στήνεται μια νέα εγκατάσταση

Δεν υπάρχει οδηγός εγκατάστασης για ένα νέο στήσιμο — εισάγετε απευθείας το σχήμα και ρυθμίζετε το αρχείο περιβάλλοντος.

1. Εγκαταστήστε τις εξαρτήσεις PHP:
   composer install
2. Αντιγράψτε το πρότυπο αρχείο περιβάλλοντος και συμπληρώστε τα διαπιστευτήρια της βάσης δεδομένων σας:
   cp .env.example .env
3. Εισαγάγετε το database/production.sql στη βάση δεδομένων που ορίζεται στο .env σας — έτσι δημιουργείται ολόκληρο το σχήμα.
4. Αντικαταστήστε τον προεγκατεστημένο λογαριασμό διαχειριστή (δείτε την επισήμανση παρακάτω) και μετά συνδεθείτε στο /admin/.

Για τοπική ανάπτυξη, ο ενσωματωμένος διακομιστής της PHP λειτουργεί χωρίς Apache: php -S localhost:8000 router.php — προσοχή, αυτός ο διακομιστής αγνοεί εντελώς το .htaccess, οπότε το router.php υλοποιεί ξανά τους ίδιους κανόνες δρομολόγησης με το χέρι (δείτε Ρύθμιση διακομιστή web).

Μεταβλητές περιβάλλοντος

Όλες οι ρυθμίσεις που αφορούν το εκάστοτε περιβάλλον βρίσκονται στο .env και φορτώνονται μέσω του vlucas/phpdotenv. Αντιγράψτε το .env.example σε .env (το git το αγνοεί) και ορίστε πραγματικές τιμές για κάθε περιβάλλον — τουλάχιστον τα διαπιστευτήρια της βάσης δεδομένων, πριν από την εισαγωγή του σχήματος.

Οι ρυθμίσεις που ισχύουν για όλο το site και δεν εξαρτώνται από το περιβάλλον (όνομα εφαρμογής, νόμισμα, ενεργά πρόσθετα, ενεργό θέμα και οι διακόπτες κάθε κάθετης ενότητας) βρίσκονται στη βάση δεδομένων, στον tbl_settings, και τις διαχειρίζεστε από τον πίνακα διαχείρισης αντί για αρχεία.

Ρύθμιση διακομιστή web

Οι κανόνες δρομολόγησης και ασφάλειας — φιλικά URL, αποκλεισμός άμεσης πρόσβασης σε .env/connection.php/αρχεία καταγραφής και αποτροπή της εκτέλεσης ανεβασμένου περιεχομένου ως PHP — ορίζονται σε αρχεία .htaccess σε όλο το έργο. Ο Apache και ο LiteSpeed/OpenLiteSpeed τα διαβάζουν αυτούσια.

Στον nginx, χρησιμοποιήστε το nginx.conf.example, που αναπαράγει όλους αυτούς τους κανόνες ως ένα μπλοκ server{} του nginx — προσαρμόστε τα server_name, root και το socket του PHP-FPM στο δικό σας περιβάλλον.

Αρχιτεκτονική αιτημάτων

Κάθε σελίδα του καταστήματος (index.php, item.php, …) ξεκινά μέσα από το includes/header.php, με αυτή τη σειρά:

Το connection.php ξεκινά τη συνεδρία, συνδέεται μέσω mysqli με τα διαπιστευτήρια του .env, φορτώνει τον tbl_settings σε σταθερές όπως APP_NAME και CURRENCY και συνδέει τον τρέχοντα χρήστη μαζί με μια εγγραφή αποτυπώματος συσκευής. Η plugins_load() φορτώνει κάθε ενεργό πρόσθετο και πυροδοτεί το hook plugins_loaded — σε αυτό ακριβώς το σημείο γίνεται γνωστό το πραγματικό, τρέχον σύνολο των ενεργών κάθετων ενοτήτων, και γι' αυτό το header.php ελέγχει ξανά στη συνέχεια τις παλιές σημαίες των ρυθμίσεων (κατάστημα, πολλαπλοί πωλητές, δημοπρασία, λαχείο) απέναντι στην πραγματική κατάσταση των ενεργών πρόσθετων.

Ο πίνακας διαχείρισης δεν επαναλαμβάνει αυτή τη διαδικασία εκκίνησης — το admin/includes/connection.php ορίζει ρυθμίσεις συνεδρίας/σφαλμάτων ειδικά για τη διαχείριση και μετά συμπεριλαμβάνει το ίδιο includes/connection.php της ρίζας.

Σύστημα πρόσθετων

Ένα πρόσθετο είναι το plugins/<slug>/plugin.php — μεταδεδομένα σε σχόλιο κεφαλίδας που διαβάζονται χωρίς να εκτελεστεί το αρχείο — συν ένα προαιρετικό plugin.json για πληρέστερες πληροφορίες καταλόγου. Τα ενεργά πρόσθετα αποθηκεύονται ως πίνακας JSON στο tbl_settings.active_plugins.

• Ιδιοκτησία των πινάκων — κάθε πρόσθετο ορίζει το δικό του includes/schema.php, που καλείται κατά την ενεργοποίηση, χρησιμοποιώντας την idempotent βοηθητική συνάρτηση db_delta() (CREATE TABLE IF NOT EXISTS + μόνο προσθετικά ALTER TABLE ADD COLUMN). Ένα πρόσθετο δεν αγγίζει ποτέ τους πίνακες άλλου πρόσθετου.
• Τα μητρώα φορτώνονται πρώτα — οι add_admin_page, add_route, add_cron_job, add_api_route και register_module ορίζονται όλες πριν φορτωθεί οποιοδήποτε πρόσθετο, ώστε οι κλήσεις που κάνει ένα πρόσθετο στο ανώτατο επίπεδο να μην προκαλούν ποτέ μοιραίο σφάλμα, ακόμη κι αν το πρόσθετο τελικά μείνει ανενεργό.
• Καθαρή αφαίρεση — η διαγραφή ενός πρόσθετου εκτελεί το uninstall.php του και αφαιρεί τον φάκελό του· τίποτα έξω από το plugins/<slug>/ δεν πρέπει να απαιτεί υποχρεωτικά τα αρχεία του, ώστε το υπόλοιπο site να συνεχίζει να δουλεύει και χωρίς αυτό.

Σύστημα θεμάτων

Ένα θέμα βρίσκεται στο assets/themes/<slug>/ — ένα manifest.php, ένα theme.css, ένα functions.php για τα hooks του θέματος και ένας προαιρετικός φάκελος components/. Το ενεργό θέμα αποθηκεύεται στο tbl_settings.active_theme, με το editorial ως εφεδρική επιλογή αν δεν έχει οριστεί κάποιο.

Η εύρεση ενός component γίνεται με αυτή τη σειρά: πρώτα ο φάκελος components/ του ίδιου του ενεργού θέματος, μετά ο φάκελος components που δηλώνει ένα πρόσθετο μέσω register_module() και τέλος ο κοινός components/ της ρίζας. Στην πράξη αυτό σημαίνει ότι η κοινή προεπιλογή υπάρχει μία φορά στο components/ και κάθε θέμα — ή ενεργό πρόσθετο κάθετης ενότητας — μπορεί να αντικαταστήσει μια συγκεκριμένη διαδρομή component με το δικό του αντίγραφο.

Βάση δεδομένων

Πρόθεμα πινάκων tbl_, καθαρό mysqli, κυρίως prepared statements. Τα αρχεία SQL, κατά σειρά ισχύος:

• database/core-schema.sql — μόνο οι πίνακες του πυρήνα, που συντηρούνται με το χέρι· οι πίνακες των κάθετων ενοτήτων και των πρόσθετων εξαιρούνται σκόπιμα.
• database/production.sql — παράγεται αυτόματα (σχήμα πυρήνα + η ρουτίνα εγκατάστασης κάθε πρόσθετου, με dump από μια πρόχειρη βάση δεδομένων). Αυτό εισάγετε για μια νέα εγκατάσταση.
• database/sandbox.sql — σύνολο δεδομένων επίδειξης για τοπική ανάπτυξη.
• database/migration.sql — ενοποιημένο, idempotent σενάριο αναβάθμισης για υπάρχουσες εγκαταστάσεις.
• database/migrations/<slug>/up.sql (+ down.sql όπου είναι αναστρέψιμη) — ένα αρχείο ανά μεμονωμένη μετάπτωση.

Ενότητες

Κάθε ενότητα περιλαμβάνεται στην ίδια εγκατάσταση και ενεργοποιείται ή απενεργοποιείται ανεξάρτητα από τον πίνακα διαχείρισης.

Δημοπρασίες

Ζωντανές προσφορές με περιβάλλον πωλητών για πολλαπλούς πωλητές και μηχανισμό προμηθειών. Βασικό πρόσθετο: plugins/auction.

Λαχείο

Κληρώσεις με λαχνούς, με ρυθμιζόμενα προγράμματα, βραβεία και ειδοποιήσεις νικητών. Βασικό πρόσθετο: plugins/lottery.

Mystery box

Ρυθμιζόμενα σύνολα βραβείων με animation αποκάλυψης — οι χρήστες αγοράζουν ένα κουτί και βλέπουν αμέσως τι κέρδισαν. Πρόσθετο: plugins/mystery-box.

Παιχνίδια & ανταμοιβές

Μια συστάδα arcade παιχνιδιών μέσα στο games/, συν πρόσθετα συμμετοχής και κερδών:

Κατάστημα & marketplace

Ένα επίπεδο e-commerce για πολλαπλούς πωλητές, με προωθητικές ενέργειες και εργαλεία προβολής προϊόντων. Βασικά πρόσθετα: plugins/shop, plugins/multivendor.

Πορτοφόλι, νομίσματα & επενδύσεις

Ένα πορτοφόλι σε επίπεδο πλατφόρμας, κοινό για όλες τις ενότητες.

Παραπομπές & ανταμοιβές

Ταυτοποίηση, εμπιστοσύνη & συμμόρφωση

Βοηθητικά εργαλεία

Πίνακας διαχείρισης

Ο πίνακας διαχείρισης βρίσκεται στο admin/ και δεν επαναλαμβάνει τη διαδικασία εκκίνησης του καταστήματος — ορίζει ρυθμίσεις συνεδρίας/σφαλμάτων ειδικά για τη διαχείριση και μετά συμπεριλαμβάνει το ίδιο includes/connection.php της ρίζας. Οι σελίδες δηλώνονται μέσω της add_admin_page(), η οποία αναλαμβάνει την καταχώριση στο πλαϊνό μενού, τον έλεγχο δικαιωμάτων, το CSRF και το πλαίσιο ταυτοποίησης· οι ενέργειες JSON που αφορούν μόνο τη διαχείριση δηλώνονται μέσω της add_admin_ajax() και δρομολογούνται από το admin/ajax.php?action=<slug>.

Θέματα καταστήματος

Πέντε θέματα περιλαμβάνονται στο assets/themes/ και αλλάζουν ανά εγκατάσταση από τον πίνακα διαχείρισης. Κάθε θέμα κρατά το δικό του αντίγραφο των κοινών components στον δικό του φάκελο components/.

Πύλες πληρωμών

Οι 38 αυτόματες πύλες ανήκουν σε πρόσθετα — η καθεμία βρίσκεται στον δικό της φάκελο plugins/gateway-<slug>/ και δηλώνεται στον πυρήνα μέσω της add_payment_gateway(). Μόλις ενεργοποιήσετε μία, απλώς δουλεύει· τίποτα στον δρομολογητή του ταμείου (payment_processor.php) δεν είναι γραμμένο σταθερά για μια συγκεκριμένη πύλη.

Οι 3 χειροκίνητες μέθοδοι είναι εγγραφές gateway_type = 'manual' που εισάγονται από τον πυρήνα και δεν έχουν κώδικα init/verify προς ρύθμιση — απλώς εμφανίζουν οδηγίες πληρωμής ή έναν κωδικό QR. Το πρόσθετο manual-gateway-builder επιτρέπει σε έναν διαχειριστή να προσθέσει κι άλλες προσαρμοσμένες χειροκίνητες μεθόδους πληρωμής χωρίς να αγγίξει κώδικα.

Ορισμένες πύλες (Stripe, Razorpay, Midtrans, Venmo) δηλώνουν επιπλέον ένα hook render για ροές ταμείου που χρειάζονται JS στην πλευρά του πελάτη — μια εκκίνηση του Stripe Checkout ή ένα SDK Razorpay/Midtrans/Braintree που χρειάζεται πρώτα ένα ID παραγγελίας ή ένα token φτιαγμένο στον διακομιστή. Κάθε άλλη πύλη λειτουργεί χωρίς καμία επιπλέον παρέμβαση στον πυρήνα.

Επίπεδα API & AJAX

• api/v1/ — REST API με ταυτοποίηση JWT, για την εφαρμογή κινητού και για εξωτερικούς καταναλωτές. Το api/v1/middleware/*.php ελέγχει την κεφαλίδα Authorization: Bearer <token>. Τα πρόσθετα προσθέτουν τα δικά τους endpoints μέσω της add_api_route().
• ajax/ — εσωτερικό AJAX με ταυτοποίηση μέσω cookie συνεδρίας, για τη JS του ίδιου του καταστήματος (καλάθι, κουπόνια, ειδοποιήσεις). Χωρίς επίπεδο token — στηρίζεται στη συνεδρία PHP που στήνει το connection.php.
• Χαλαρό api/ στο ανώτατο επίπεδο — διάφορα endpoints χωρίς έκδοση, όπως τα geo_location.php, exchange-rate.php και offerwall_postback.php.

Εφαρμογή για κινητά

Το mobile/ είναι ξεχωριστό έργο Capacitor + Ionic — ένα περιτύλιγμα WebView γύρω από το ζωντανό site, όχι αυτόνομο SPA και όχι απλώς καταναλωτής του api/v1. Το capacitor.config.ts του δείχνει το server.url στον δικό σας τομέα. Έχει δικό του package.json και δεν χτίζεται από τη ρίζα του έργου:

Ενημερώσεις & μεταπτώσεις

Κρατήστε ένα αντίγραφο πριν εκτελέσετε το database/migration.sql ή οποιοδήποτε database/migrations/<slug>/up.sql σε ζωντανή βάση δεδομένων:

Οι περισσότερες μεταπτώσεις συνοδεύονται από ένα αντίστοιχο down.sql που αναιρεί μόνο τη συγκεκριμένη αλλαγή. Λίγες από αυτές, που μετασχηματίζουν υπάρχοντα δεδομένα αντί να προσθέτουν μόνο δομή, συνοδεύονται από ένα down.sql που εξηγεί γιατί δεν κάνει τίποτα — σε αυτές τις περιπτώσεις, αν χρειαστεί να γυρίσετε πίσω, επαναφέρετε το dump που κρατήσατε πριν την ανάπτυξη.

Σημειώσεις ασφάλειας

• Αλλάξτε αμέσως μετά την εισαγωγή τα προεγκατεστημένα διαπιστευτήρια του διαχειριστή (δείτε Εγκατάσταση).
• Τα .env, connection.php και τα αρχεία καταγραφής είναι αποκλεισμένα από άμεση πρόσβαση HTTP μέσω των κανόνων .htaccess / nginx που περιλαμβάνονται — μην αφαιρέσετε αυτούς τους κανόνες.
• Το περιεχόμενο που ανεβάζουν οι χρήστες σερβίρεται με τρόπο που δεν του επιτρέπει να εκτελεστεί ως PHP, και αυτό επιβάλλεται στις ρυθμίσεις του διακομιστή web, όχι στο επίπεδο της εφαρμογής.
• Τα διαπιστευτήρια των πυλών πληρωμών ρυθμίζονται ξεχωριστά για κάθε πύλη από τον πίνακα διαχείρισης και αποθηκεύονται στον διακομιστή — δεν εκτίθενται ποτέ στο κατάστημα.

Δοκιμές

Δεν υπάρχει σουίτα PHPUnit. Η εντολή composer test εκτελεί το bin/run-probes.php, το οποίο συγκεντρώνει κάθε αρχείο probe_*.php μέσα στο includes/_probes/ και στον φάκελο _probes/ κάθε πρόσθετου, τρέχει το καθένα ως υποδιεργασία CLI και ελέγχει τον κωδικό εξόδου του.

Συχνές ερωτήσεις

Υποστήριξη & πόροι

Κολλήσατε κάπου ή χρειάζεστε κάτι που δεν καλύπτει αυτή η σελίδα;