palladium
Who is that "index" and where to find it
(العمل قيد التقدم: المستندات للإصدار 2.0)
مكتبة للتعامل مع هوية المستخدم.
الغرض من هذه المكتبة هو تحديد موقع حساب المستخدم (على وجه الدقة - معرفه الفريد) لإثبات هوية معين وإدارة أنواع مختلفة من الهويات. وهو يتألف من 4 خدمات مختلفة: تحديد الهوية والتسجيل والبحث والاسترداد.
يمكنك إضافة المكتبة إلى مشروعك باستخدام الملحن باستخدام الأمر التالي:
composer require teresko/ palladiumلاستخدام هذه الحزمة، فإنها تتطلب PHP الإصدار 7.0+ وPDO.
ستحتاج أيضًا إلى إنشاء جدول لتخزين الهويات . مخطط المثال متاح هنا. وهي تحتوي حاليًا على تعريف جدول فقط لـ MySQL/MariaDB، ولكن يمكن استخدام المكتبة مع أي RDBMS، الذي يحتوي على برنامج تشغيل PDO.
palladium يحتوي على 4 خدمات: Registration Identification Search Recovery . تحتوي كل خدمة من هذه الخدمات على تبعيتين إلزاميتين:
palladium ContractCanPersistIdenity )PsrLogLoggerInterface )يمنحك هذا خيارًا لاستبدال المستودع الافتراضي، إذا كنت تريد تغيير أو استبدال أجزاء من طبقة التجريد المستمرة. أما بالنسبة للمسجل - فالأسلوب الموصى به هو استخدام Monolog، ولكنه سيعمل مع أي نظام تسجيل متوافق.
يأتي المستودع الافتراضي أيضًا مزودًا بوظيفة إضافة أنواع هويات مخصصة ومخططات بيانات، يتم استخدامها إما لأنواع الهوية الخاصة بك أو لأنواع الهوية المضمنة. للحصول على تفاصيل الاستخدام، راجع قسم %TODO%.
يوجد في مُنشئ خدمة Identification معلمة ثالثة ورابعة اختيارية:
يوجد في مُنشئ خدمة Registration معلمة ثالثة اختيارية:
كما هو مذكور أعلاه، تتوقع جميع الخدمات الأربع وجود مستودع باعتباره تبعية منشئة. إذا كنت لا تستبدل المستودع المجمع بإصدارك المخصص، فستحتاج إلى تهيئة palladium RepositoryIdentity وتمريره إلى الخدمات.
يحتوي المستودع المجمع نفسه على تبعية واحدة: مثيل، يقوم بتنفيذ palladium ContractCanCreateMapper . يتم تنفيذ هذا العقد (الواجهة) بواسطة palladium ComponentMapperFactory . وهذا المصنع له تبعيتان: مثيل PDO واسم الجدول، حيث سيتم تخزين الهويات .
<?php
$ factory = new palladium Component MapperFactory ( new PDO (... $ config ), $ tableName );
$ repository = new palladium Repository Identity ( $ factory ); في كل مثال تعليمات برمجية آخر، حيث ترى متغير $repository مستخدمًا، يمكنك افتراض أنه تمت تهيئته باستخدام نموذج التعليمات البرمجية هذا.
بالنسبة لمستخدمي DependencyInjection Component الخاص بـ Symfony (الإصدار: 3.4+)، يوجد نموذج لملف التكوين: %TODO%
<?php
$ registration = new palladium Service Registration ( $ repository , $ logger );
$ identity = $ registration -> createStandardIdentity ( ' [email protected] ' , ' password ' );
$ registration -> bindAccountToIdentity ( $ accountId , $ identity ); إذا اكتملت العملية بنجاح، فسيحتوي المتغير $identity على مثيل StandardIdentity الذي لم يتم التحقق منه. لإكمال عملية التحقق، سيتعين عليك استخدام الرمز المميز الذي تحتويه الهوية. في المثال الموضح، يمكن تقييم هذا الرمز المميز باستخدام $instance->getToken() .
يمكن للأسلوب createStandardIdentity() طرح استثناء IdentityConflict ، إذا كان البريد الإلكتروني قد استخدم بالفعل لهوية أخرى.
يحتوي الأسلوب createStandardIdentity() على معلمة ثالثة اختيارية تحدد العمر الافتراضي للرمز المميز للتحقق من البريد الإلكتروني بالثواني. عند تطبيقه، يبدو المثال السابق كما يلي:
<?php
$ registration = new palladium Service Registration ( $ repository , $ logger );
$ identity = $ registration -> createStandardIdentity ( ' [email protected] ' , ' password ' , 3600 );
$ registration -> bindAccountToIdentity ( $ accountId , $ identity ); سيؤدي هذا إلى جعل رمز التحقق قابلاً للاستخدام لمدة ساعة واحدة بعد تسجيل هوية هذا المستخدم. بعد مرور الوقت المحدد، لن تتمكن من العثور على هذه الهوية باستخدام findStandardIdentityByToken() في خدمة Search .
هام : لا تتحقق أساليب
createStandardIdentity()من صحة البريد الإلكتروني للمستخدمين أو أي نوع آخر من المعرفات. إنه يتحقق فقط من تفرده. التحقق من صحة رسائل البريد الإلكتروني وأرقام الهواتف والألقاب والمعرفات الأخرى يقع خارج نطاق هذه المكتبة.
<?php
$ search = new palladium Service Search ( $ repository , $ logger );
$ registration = new palladium Service Registration ( $ repository , $ logger );
$ identity = $ search -> findStandardIdentityByToken ( $ token , palladium Entity Identity:: ACTION_VERIFY );
$ registration -> verifyStandardIdentity ( $ identity ); يتم استخدام قيمة $token لتحديد EmailIdentity المطابق، والذي يتم بعد ذلك التحقق منه. إذا لم يتم العثور على الهوية، فسوف يقوم findStandardIdentityByToken() بطرح استثناء IdentityNotFound .
<?php
$ search = new palladium Service Search ( $ repository , $ logger );
$ identification = new palladium Service Identification ( $ repository , $ logger );
$ identity = $ search -> findStandardIdentityByIdentifier ( $ identifier );
$ cookie = $ identification -> loginWithPassword ( $ identity , $ password ); إذا لم يتم العثور على هوية مطابقة مع معرف معين (مثل عنوان البريد الإلكتروني)، فسوف تقوم طريقة findStandardIdentityByIdentifier() بطرح استثناء IdentityNotFound .
في حالة عدم تطابق كلمة المرور، فسيطرح الأسلوب loginWithPassword() استثناءً PasswordMismatch .
<?php
$ identity = $ this -> registration -> createNonceIdentity ( $ accountId ); سيؤدي هذا إلى إنشاء مثيل جديد لـ NonceIdentity . لاستخدامه لتسجيل الدخول، ستحتاج إلى قيم في NonceIdentity::getIdentifier() و NonceIdentity::getKey() ، حيث سيتم استخدام المعرف لتحديد هوية nonce وسيتم استخدام المفتاح للتحقق.
كانت طريقة createNonceIdentity() عبارة عن معلمة ثانية اختيارية تحدد عمر هوية الاستخدام الفردي هذه بالثواني. عند تطبيقه، يبدو المثال السابق كما يلي:
<?php
$ identity = $ this -> registration -> createNonceIdentity ( $ accountId , 600 ); سيؤدي هذا إلى جعل الهوية ذات الاستخدام الواحد قابلة للاستخدام لمدة 10 دقائق بعد إنشائها. بعد مرور الوقت المسموح به، سيؤدي تمرير هذه الهوية في طريقة useNonceIdentity() Identification إلى طرح استثناء IdentityExpired .
<?php
$ identity = $ this -> search -> findNonceIdentityByIdentifier ( $ identifier );
$ cookie = $ this -> identification -> useNonceIdentity ( $ identity , $ key ); إذا لم يتم العثور على هوية مطابقة مع المعرف المحدد (عنوان البريد الإلكتروني، اللقب، إلخ.)، فسوف تقوم طريقة findNonceIdentityByIdentifier() بطرح استثناء IdentityNotFound .
في حالة عدم تطابق كلمة المرور، فسيقوم الأسلوب useNonceIdentity() بطرح استثناء KeyMismatch .
<?php
$ search = new palladium Service Search ( $ repository , $ logger );
$ identification = new palladium Service Identification ( $ repository , $ logger );
$ identity = $ search -> findCookieIdentity ( $ accountId , $ series );
$ cookie = $ identification -> loginWithCookie ( $ identity , $ key ); إذا لم يتم العثور على ملف تعريف الارتباط باستخدام findCookieIdentity() فسيتم طرح استثناء IdentityNotFound القياسي. قد يكون السبب المحتمل لذلك إما أن ملف تعريف الارتباط لم يعد نشطًا (على سبيل المثال قام المستخدم بتسجيل الخروج) أو أن ملف تعريف الارتباط غير موجود على الإطلاق.
في حالة ما إذا كان ملف تعريف الارتباط قديمًا جدًا، فسينتج loginWithCookie() استثناء IdentityExpired .
لكن طريقة loginWithCookie() يمكنها أيضًا إنتاج استثناء CompromisedCookie . قد تشير رؤية استثناء لهذا إلى أن ملف تعريف الارتباط قد تمت سرقته أو أن المستخدم لم يتلق قيمة ملف تعريف ارتباط جديدة مطلقًا.
<?php
$ search = new palladium Service Search ( $ repository , $ logger );
$ identification = new palladium Service Identification ( $ repository , $ logger );
$ identity = $ search -> findCookieIdentity ( $ accountId , $ series );
$ identification -> blockIdentity ( $ identity );هذه هي الطريقة الموصى بها للتعامل مع ملفات تعريف الارتباط المشبوهة، والتي قد تكون مسروقة أو لا. هذا ليس مخصصًا لتسجيل خروج المستخدمين .
<?php
$ search = new palladium Service Search ( $ repository , $ logger );
$ identification = new palladium Service Identification ( $ repository , $ logger );
$ identity = $ search -> findCookieIdentity ( $ accountId , $ series );
$ identification -> logout ( $ identity , $ key );تضع هذه العملية علامة على ملف تعريف الارتباط على أنه "تم تجاهله". تتطابق قائمة الاستثناءات التي يمكن إنتاجها مع تلك الموضحة في قسم تسجيل الدخول باستخدام ملفات تعريف الارتباط.
<?php
$ search = new palladium Service Search ( $ repository , $ logger );
$ recovery = new palladium Service Recovery ( $ repository , $ logger );
$ identity = $ search -> findStandardIdentityByIdentifier ( $ identifier );
$ token = $ recovery -> markForReset ( $ identity ); إذا لم يتم العثور على هوية مطابقة مع عنوان البريد الإلكتروني المحدد، فسوف تقوم طريقة findStandardIdentityByIdentifier() بطرح استثناء IdentityNotFound .
عند استدعاء markForReset() ، يجب أن يتم تزويده بمثيل StandardIdentity ، الذي تم التحقق منه بالفعل (وإلا فمن المحتمل أن يتسبب في تسرب معلومات المستخدم الخاصة من تطبيقك). إذا لم يكن الأمر كذلك، فسوف تقوم الطريقة بطرح استثناء IdentityNotVerified .
كانت طريقة markForReset() عبارة عن معلمة ثانية اختيارية تحدد العمر الافتراضي لرمز إعادة تعيين كلمة المرور بالثواني. عند تطبيقه، يبدو المثال السابق كما يلي:
<?php
$ search = new palladium Service Search ( $ repository , $ logger );
$ recovery = new palladium Service Recovery ( $ repository , $ logger );
$ identity = $ search -> findStandardIdentityByIdentifier ( $ identifier );
$ token = $ recovery -> markForReset ( $ identity , 7200 ); سيؤدي هذا إلى جعل رمز إعادة تعيين كلمة المرور قابلاً للاستخدام لمدة ساعتين بعد تحديد هوية هذا المستخدم لإعادة تعيينها. عند انتهاء الوقت المسموح به، لن تتمكن من العثور على هذه الهوية باستخدام findEmailIdentityByToken() في خدمة Search .
<?php
$ search = new palladium Service Search ( $ repository , $ logger );
$ recovery = new palladium Service Recovery ( $ repository , $ logger );
$ identity = $ search -> findEmailIdentityByToken ( $ token , palladium Entity Identity:: ACTION_RESET );
$ recovery -> resetIdentityPassword ( $ identity , ' foobar ' ); إذا لم يتم العثور على هوية مطابقة مع الرمز المميز المحدد، فسوف تقوم طريقة findEmailIdentityByToken() بطرح استثناء IdentityNotFound .
<?php
$ search = new palladium Service Search ( $ repository , $ logger );
$ identification = new palladium Service Identification ( $ repository , $ logger );
$ identity = $ search -> findStandardIdentityByIdentifier ( $ identifier );
$ identification -> changePassword ( $ identity , $ oldPassword , $ newPassword ); إذا لم يتم العثور على هوية مطابقة مع عنوان البريد الإلكتروني المحدد (أو أي نوع آخر من المعرفات)، فستطرح طريقة findStandardIdentityByIdentifier() استثناء IdentityNotFound .
في حالة عدم تطابق كلمة المرور، فسيطرح الأسلوب changePassword() استثناءً PasswordMismatch .
<?php
$ search = new palladium Service Search ( $ repository , $ logger );
$ identification = new palladium Service Identification ( $ factory , $ logger );
$ list = $ search -> findIdentitiesByParentId ( $ identity -> getId ());
$ identification -> discardIdentityCollection ( $ list ); القيمة المرجعة لـ findIdentitiesByParentId() ستُرجع IdentityCollection ، والتي يمكن أن تكون فارغة.
كما ذكرنا سابقًا، تتوقع الخدمات الموجودة في هذه المكتبة وجود مسجل متوافق مع PSR-3 باعتباره تبعية. سيتم استخدامه لتسجيل ثلاثة مستويات من الأحداث:
LogLevel::INFOيتم استخدام مستوى السجل هذا لتتبع العمليات العادية التي قد يقوم بها المستخدم عند استخدام التطبيق الخاص بك بالطريقة المقصودة:
LogLevel::NOTICEسيتم تسجيل السجلات بهذا المستوى، إذا حاول المستخدم إجراء عملية غير ناجحة، فلا ينبغي أن يحدث ذلك في سيناريوهات الاستخدام الصحيحة:
LogLevel::WARNINGيُستخدم فقط لتسجيل الحالات، عندما يحاول المستخدم استخدام ملف تعريف ارتباط مخترق.
تركز هذه المكتبة على مهمة واحدة محددة. ولا يتضمن أيًا من الوظائف التالية:
إذا كنت تعتقد أن مكتبة المصادقة هذه تتطلب أحد الأجزاء المذكورة أعلاه، فهذه ليست المكتبة التي تبحث عنها.
