Hacktoberfest 2026: những issue maintainer đã đánh dấu cho tháng Mười, đang mở và phù hợp người mới. Xem issue Hacktoberfest

[RFC]: Mark PhpDb\Sql abstract classes and interfaces @api or @internal

Đang mở
  • Có gì không ổn?
#214 0 bình luận 0 reaction 0 người được giao Xem trên GitHub

Maintainer thường phản hồi trong vòng 1 ngày

Chưa có ai nhận issue này.

Đánh giá

Độ khó
3/5
Thời gian dự kiến
1-2 ngày
Mức phù hợp với người mới
66/100
Loại issue
Tài liệu
Độ rõ ràng
Khá rõ ràng
Mức độ hoạt động
Sôi nổi
Công nghệ
php
Lĩnh vực
documentation

Hướng nghiên cứu

Chạy mago analyze --ignore-baseline src/Sql (sau khi áp dụng kiểu docblock #204) để liệt kê 16 kết quả missing-api-or-internal, sau đó thêm docblock @api cho từng interface và lớp trừu tượng có tên dưới src/Sql. Đối với đề xuất 3, định vị AbstractSql và kiểm tra các điểm gọi các phương thức protected của nó để quyết định phương thức nào là @internal. Xong khi lần chạy analyze báo cáo không còn kết quả nào và mục baseline được xóa.

Do mô hình lập chỉ mục viết ra từ nội dung của issue.

Mô tả

RFC
Proposed Version

Next minor

Basic Information

Mago reports 16 missing-api-or-internal findings in src/Sql, all baselined. Each one is an abstract class or interface without an @api or @internal annotation:

  • Abstract classes: AbstractSql, AbstractPreparableSql, AbstractExpression, Ddl\Column\{AbstractLengthColumn, AbstractPrecisionColumn, AbstractTimestampColumn}, Ddl\Constraint\AbstractConstraint, Ddl\Index\AbstractIndex
  • Interfaces: SqlInterface, PreparableSqlInterface, ExpressionInterface, ArgumentInterface, PredicateInterface, Platform\PlatformDecoratorInterface, Ddl\Column\ColumnInterface, Ddl\Constraint\ConstraintInterface
Background

These are the types the driver packages and applications build on: decorators extend the statement classes through AbstractSql and AbstractPreparableSql, and implement PlatformDecoratorInterface (see #175). Metadata marked its source classes @api.

Considerations
  • The annotations are documentation only, with no runtime effect.
  • @api commits to keeping a type's public and protected surface stable within a minor release. @internal tells consumers not to depend on it.
Proposal(s)
  1. Mark every interface above @api.
  2. Mark the abstract classes @api, since drivers extend them.
  3. Mark protected methods of AbstractSql that only the library itself calls @internal, so they can change without a major release.
Appendix/Additional Info

Finding counts are from mago analyze --ignore-baseline src/Sql once the docblock typing in #204 is applied.

Ngôn ngữ chính
PHP
Star
18
Fork
8
Merge trung bình
6 ngày 11 giờ
Pull request đã merge (30 ngày)
14

Chuẩn bị môi trường

  • Có Dockerfile hoặc tệp Docker Compose
  • Không có mẫu pull request
  • Không có hướng dẫn đóng góp

Bắt đầu từ đâu

  1. Đọc hết issue, rồi đọc hướng dẫn đóng góp của dự án.
  2. Bình luận trên issue rằng bạn sẽ nhận — tránh hai người làm cùng một việc.
  3. Fork repository và làm thay đổi trên một nhánh.
  4. Mở pull request có tham chiếu số hiệu của issue.

Issue khác của php-db/phpdb

Tất cả issue của php-db/phpdb

Issue tương tự

Thêm issue về PHP

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.